{"id":15950114,"url":"https://github.com/sebastian-software/preppy","last_synced_at":"2025-03-16T07:31:43.814Z","repository":{"id":42702255,"uuid":"106252647","full_name":"sebastian-software/preppy","owner":"sebastian-software","description":"A simple and lightweight tool for preparing the publish of NPM packages.","archived":false,"fork":false,"pushed_at":"2023-02-12T02:15:01.000Z","size":9967,"stargazers_count":34,"open_issues_count":6,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-24T14:10:14.433Z","etag":null,"topics":["bundling","esm","jsx","library","npm","npm-publish","react","rollup","tooling","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sebastian-software.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-09T07:49:52.000Z","updated_at":"2024-06-18T19:58:50.893Z","dependencies_parsed_at":"2024-06-18T19:58:31.606Z","dependency_job_id":"11b489bb-31b2-421c-bec8-22a0593b2525","html_url":"https://github.com/sebastian-software/preppy","commit_stats":null,"previous_names":["sebastian-software/simplepublish"],"tags_count":234,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastian-software%2Fpreppy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastian-software%2Fpreppy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastian-software%2Fpreppy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sebastian-software%2Fpreppy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sebastian-software","download_url":"https://codeload.github.com/sebastian-software/preppy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806031,"owners_count":20350773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundling","esm","jsx","library","npm","npm-publish","react","rollup","tooling","typescript"],"created_at":"2024-10-07T12:58:08.887Z","updated_at":"2025-03-16T07:31:42.847Z","avatar_url":"https://github.com/sebastian-software.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# _Preppy_\n\n**An incredibly simple and lightweight tool for preparing packaging for the publishing process.**\n\n\u003cimg src=\"https://raw.githubusercontent.com/sebastian-software/preppy/master/demo.gif?raw=true\" alt=\"Demo of Preppy\" /\u003e\n\n\u003cbr/\u003e[![Sponsored by][sponsor-img]][sponsor] [![Version][npm-version-img]][npm] [![Downloads][npm-downloads-img]][npm] [![Build Status][github-img]][github]\n\n[sponsor]: https://www.sebastian-software.de\n[npm]: https://www.npmjs.com/package/preppy\n[sponsor-img]: https://badgen.net/badge/Sponsored%20by/Sebastian%20Software/c41e54\n[npm-downloads-img]: https://badgen.net/npm/dm/preppy\n[npm-version-img]: https://badgen.net/npm/v/preppy\n[github]: https://github.com/sebastian-software/preppy/actions\n[github-img]: https://badgen.net/github/status/sebastian-software/preppy?label=tests\u0026icon=github\n\n## 🥁 Features:\n\n- Rock solid infrastructure. Builds on well maintained [Acorn](https://github.com/acornjs/acorn), [Babel](https://babeljs.io/) and [Rollup](https://rollupjs.org/) under the hood.\n- Supports multiple entries (cli, client, server, library, ...) - even multiple binary entries.\n- Creates multiple output formats (ESM, CommonJS, UMD, ...)\n- Exports _TypeScript_ definitions (respects `types` definition in `package.json`).\n- _Lazy JSX_ support (powered by a [custom Rollup plugin](https://github.com/rollup/rollup/issues/2822)) to keep JSX intact while bundling. Major benefit for e.g. UI components: This moves decision over JSX debug capabilities or optimization settings into the application space.\n- Rebases assets to the bundled output destination. Say hello to images, web fonts, and more. It also supports assets references in CSS/SCSS.\n- Includes a _watch mode_ for live development. Very useful for developing libraries.\n- New: Deep bundling allows Webpack-like bundling where content from `node_modules` in bundled as well. By default only local code is bundled.\n- Supports auto-executing binaries. This is _super useful_ when dealing with development web servers for example.\n- Offers builds by compressing bundles with _Terser_ as needed (for files with `.min` in their name).\n- Prints out generated file sizes of all bundles.\n- Injects common env-variables into the build (`BUNDLE_{NAME|VERSION|TARGET}`). Also `NODE_ENV` for all UMD builds.\n- Executes Babel with an environment based on `NODE_ENV` but with additional data from the `target` (e.g. `node`, `lib` or `cli`) and the output `format` (e.g. `esm`, `cjs`)\n- Supports _JSON_ out of the box and inlines the serialized content into the bundle.\n\n## 🔧 Installation:\n\nFor Preppy itself installation is done by executing one command.\n\n```console\n$ npm install -D preppy\n```\n\nDepending on your transpiling needs you need Babel with the requires presets/plugins. This is nothing extra to install typically as you might have these things in-place already. Example:\n\n```console\n$ npm install -D @babel/plugin-transform-runtime @babel/preset-env @babel/preset-typescript @babel/core\n$ npm install @babel/runtime core-js\n```\n\nPlease note: Since Preppy v11 Node v16 is the minimum required version!\n\n## 🔨 Configure Babel\n\nAs transpiling happens via Babel you have to install the _Babel_ Core, Plugins and Presets on your own. You also need to use a standard Babel Configuration inside your package.\n\nExample `babel.config.json`:\n\n```json\n{\n  \"plugins\": [\n    [\n      \"@babel/transform-runtime\",\n      {\n        \"corejs\": 3\n      }\n    ]\n  ],\n  \"presets\": [\n    [\n      \"@babel/env\",\n      {\n        \"useBuiltIns\": \"usage\",\n        \"corejs\": 3\n      }\n    ],\n    [\n      \"@babel/typescript\",\n      {\n        \"allExtensions\": true,\n        \"isTSX\": true\n      }\n    ]\n  ]\n}\n```\n\nNote: `env` gets a lot more depth when working with _Preppy_. It's actually set to this: `${env}-${target}-${format}` e.g. `\"development-browser-esm\"`. This gives you more control e.g. more setting up targets for _Browserslist_.\n\nNote: Leave out the `\"@babel/typescript\"` when you do not need TypeScript transpiling.\n\nNote: Please disable `transform-runtime` for all UMD builds as UMD is better working when only clean named imports are kept external.\n\n## 📦 Usage:\n\nTo keep things simple and reduce to number of dependencies, _Preppy_ uses your local Babel configuration to transpile your code. You have to make sure that all required Babel mechanics, presets and plugins are installed locally to your project.\n\nPreppy also support extracting _TypeScript_ types into `.d.ts` files to make them usable by users of your libraries. The generated code is still transpiled by Babel. The standard `typescript` CLI is used for extracting the types.\n\n### Input Files\n\nThese are the typical entry points looked up for by _Preppy_:\n\n- `src/index.{js|jsx|ts|tsx}`\n\nWe made the experience that this works pretty fine for most projects. If you have the need for more input files, please report back to us.\n\n### Output Targets\n\n_Preppy_ produces exports of your sources depending on the entries of your packages `package.json`. It supports building for _ESM_, _CommonJS_ and _UMD_. Just add the relevant entries to the package configuration.\n\n- _CommonJS_: `main`\n- _EcmaScript Modules (ESM)_: `module`: New module standard for optimal tree shaking of bundlers.\n- _Universal Module Definition (UMD)_: `umd` + `unpkg` for delivering a minified bundle to the CDN.\n\nBasic Example:\n\n```json\n{\n  \"name\": \"mypackage\",\n  \"main\": \"lib/index.cjs.js\",\n  \"module\": \"lib/index.esm.js\",\n  \"unpkg\": \"lib/index.umd.min.js\"\n}\n```\n\nFor exporting types with TypeScript you should add a `types` entry to your `package.json` as well:\n\n```json\n{\n  \"name\": \"mypackage\",\n  \"main\": \"lib/index.cjs.js\",\n  \"module\": \"lib/index.esm.js\",\n  \"unpkg\": \"lib/index.umd.min.js\",\n  \"types\": \"lib/index.d.ts\"\n}\n```\n\n### Binary Output(s)\n\nAdditionally _Preppy_ is capable in generating for binary targets e.g. CLI tools. Not just one, but each of the one listed in the `bin` section of your `package.json`.\n\nThe following example generates a `mycli` binary which is generated from the matching source file.\n\nBinaries are generally generated from one of these source files:\n\n- `src/{name}.{js|ts}`\n- `src/cli/{name}.{js|ts}`\n- `src/cli.{js|ts}`\n- `src/cli/index.{js|ts}`\n\nExample Configuration:\n\n```json\n{\n  \"name\": \"mycli\",\n  \"bin\": {\n    \"mycli\": \"bin/mycli\"\n  }\n}\n```\n\n### Universal Output\n\n_Preppy_ also has some support for building universal libraries. While for most projects it's completely feasible\nto have one library for both NodeJS and browsers (or only for one of these), others might want (slightly) different\npackages to browsers and NodeJS.\n\nThe only difference here is that you have to define a new `browser` definition inside your `package.json`. Also\nthe input fields differ from the one of the normal libraries or binaries:\n\n- `src/client.{js|jsx|ts|tsx}`\n- `src/browser.{js|jsx|ts|tsx}`\n- `src/client/index.{js|jsx|ts|tsx}`\n- `src/browser/index.{js|jsx|ts|tsx}`\n\nFor the NodeJS part you can use any of the following entries:\n\n- `src/node.{js|jsx|ts|tsx}`\n- `src/server.{js|jsx|ts|tsx}`\n- `src/node/index.{js|jsx|ts|tsx}`\n- `src/server/index.{js|jsx|ts|tsx}`\n\nExample Configuration:\n\n```json\n{\n  \"name\": \"mylib\",\n  \"browser\": \"lib/browser.esm.js\",\n  \"unpkg\": \"lib/browser.umd.js\",\n  \"main\": \"lib/node.cjs.js\",\n  \"module\": \"lib/node.esm.js\"\n}\n```\n\nNote: The bundle under `browser` is a ESM bundle which is ideally used by bundlers like _Webpack_ or _Parcel_.\n\nNote: When any of these files exists, we use prefer it over the normal library for the `unpkg` entry in `package.json` as well.\n\n### Environment Settings\n\n_Preppy_ injects these environment values into your code base:\n\n- `process.env.BUNDLE_NAME`: Extracted `name` field from `package.json`.\n- `process.env.BUNDLE_VERSION`: Extracted `version` field from `package.json`.\n- `process.env.BUNDLE_TARGET`: One of the supported targets. Either `node`, `browser`, `lib` or `cli`.\n- `process.env.BUNDLE_ENV`: Environment name. Typical values are `development`, `production` and `test`. Use this instead of `NODE_ENV` to inject the current value at bundle time.\n\nThese values are injected into your code base by replacing the original instance.\n\nFor UMD bundles we also replace:\n\n- `process.env.NODE_ENV`: Same as `BUNDLE_ENV` - mainly replaced as this is a pretty common standard field which can't be resolved in browsers.\n\nNotes:\n\n- It only works correctly when you use the whole identifier.\n- In verbose mode we are logging the environment settings configured.\n\n### Deep Mode\n\nThis is a special mode for Preppy. Where it normally targets build steps for libraries this\nso-called _deep_ mode compares to default behavior of **Parcel** or **Webpack**. It inlines code which is defined in `node_modules` as much as possible. The logic uses information from the `package.json` file and only bundles dependencies which are defined in `devDependencies` and not in `dependencies`. All this combined with the tree-shaking capabilities of the underlying **Rollup** results into monolithic easy to deploy code with minimal external runtime dependencies. To enable deep mode pass the `--deep` flag on the CLI.\n\nNote: Using this functionality may require a bit of trial and error with the `dependencies` or `devDependecies` listed in the `package.json`. There are a few packages that cause warnings and errors when processed with Preppy's _Rollup_ engine. In these cases, these packages usually need to be kept external and remain as a entry oin `dependencies`. From experience, this problem mostly affects packages that have been implemented very close to infrastructural properties of NodeJS.\n\n### Command Line Interface\n\n_Preppy_ comes with a binary which can be called from within your `scripts` section\nin the `package.json` file.\n\n```json\n\"scripts\": {\n  \"prepare\": \"preppy\"\n}\n```\n\nThere is also some amount of parameters you can use if the auto detection of your library does not work out correctly.\n\n```\nUsage\n  $ preppy\n\nOptions\n  --entry-lib        Entry file for Library (universal) target [auto]\n  --entry-browser    Entry file for Browser target [auto]\n  --entry-node       Entry file for NodeJS target [auto]\n  --entry-cli        Entry file for CLI target [auto]\n\n  --root             The root folder of your project [auto]\n  --output           Override output folder (and package.json entries) [auto]\n  --watch            Keeps running and rebuilds on any change [false]\n  --limit            Limits the current build scope to files matching [null]\n  --deep             Produces a deep bundle which includes dependencies inline [false]\n  --exec             Executes the generated binary after creation [false]\n  --notify           Enables notifications (useful when used in watch mode) [false]\n\n  --no-sourcemap     Disables creation of a source map file during processing [false]\n\n  -v, --verbose      Verbose output mode [false]\n  -q, --quiet        Quiet output mode [false]\n```\n\n## License\n\n[Apache License; Version 2.0, January 2004](http://www.apache.org/licenses/LICENSE-2.0)\n\n## Copyright\n\n\u003cimg src=\"https://cdn.rawgit.com/sebastian-software/sebastian-software-brand/0d4ec9d6/sebastiansoftware-en.svg\" alt=\"Logo of Sebastian Software GmbH, Mainz, Germany\" width=\"460\" height=\"160\"/\u003e\n\nCopyright 2016-2022\u003cbr/\u003e[Sebastian Software GmbH](http://www.sebastian-software.de)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastian-software%2Fpreppy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsebastian-software%2Fpreppy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsebastian-software%2Fpreppy/lists"}