{"id":19234485,"url":"https://github.com/enormora/packtory","last_synced_at":"2025-04-21T05:31:01.723Z","repository":{"id":220725936,"uuid":"689977140","full_name":"enormora/packtory","owner":"enormora","description":"Effortless code bundling and publishing for npm packages","archived":false,"fork":false,"pushed_at":"2024-10-29T18:14:14.000Z","size":1286,"stargazers_count":3,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-29T20:18:02.903Z","etag":null,"topics":["bundler","bundling","monorepo","npm","package","packaging","publish","publishing","versioning"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/enormora.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":"2023-09-11T09:46:18.000Z","updated_at":"2024-10-29T18:11:43.000Z","dependencies_parsed_at":"2024-02-20T19:48:14.133Z","dependency_job_id":"07d5c02e-2816-40c6-b31d-c819d19a7d20","html_url":"https://github.com/enormora/packtory","commit_stats":null,"previous_names":["enormora/packtory"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enormora%2Fpacktory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enormora%2Fpacktory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enormora%2Fpacktory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/enormora%2Fpacktory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/enormora","download_url":"https://codeload.github.com/enormora/packtory/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223849223,"owners_count":17213640,"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":["bundler","bundling","monorepo","npm","package","packaging","publish","publishing","versioning"],"created_at":"2024-11-09T16:13:51.406Z","updated_at":"2024-11-09T16:13:51.996Z","avatar_url":"https://github.com/enormora.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n    \u003ch1\u003epacktory\u003c/h1\u003e\n    \u003cp\u003e\u003ci\u003eEffortless code bundling and publishing for npm packages\u003c/i\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n🚀 **Simplify and Automate Your Code Bundling and Publishing Workflow with packtory** 🚀\n\nTired of restrictive monorepo conventions? Fed up with complex workspace setups? Want your monorepo to feel as smooth as a single codebase, effortlessly referencing local files? Think semantic versioning (semver) adds unnecessary complexity, and every version should be treated as potentially breaking anyway? Look no further.\n\nSay goodbye to:\n\n-   🔗 Cumbersome workspaces\n-   📦 Dependency linking during development\n-   🙅‍♂️ Manual file selection (e.g. via `.npmignore` or `files`)\n-   📄 Shipping unnecessary files (e.g. build configs, tests)\n-   🔄 Manual versioning\n\n## 🌟 **Introducing packtory: Your Code Organization and Packaging Game Changer** 🌟\n\n**Key Features:**\n\n-   **Organize with Freedom**: Manage your monorepo without confining conventions or workspace limitations. packtory simplifies it, just like a single codebase.\n-   **Effortless Dependency Bundling**: Forget manual dependency linking. packtory automatically detects and bundles dependencies, freeing you to focus on your code.\n-   **Clean and Efficient Packaging**: Package only essential files, excluding devDependencies, CI configurations, and tests. Keep your npm package clean and efficient.\n-   **Revolutionary Automatic Versioning**: Choose manual versioning or let packtory handle it. In automatic mode, it calculates versions intelligently, ensuring reproducibility without complexity.\n-   **Seamless CI Pipeline Integration**: Easily integrate packtory into your CI pipelines for automatic publishing with every commit. No more intricate checks to decide what to publish.\n\n## Quick Start\n\nThe quickest way to leverage packtory is through its command-line interface (CLI).\n\n**Installation:**\n\n```bash\nnpm install -D @packtory/cli\n```\n\n**Configuration:**\n\nCreate a configuration file named `packtory.config.js` in your project's root:\n\n```js\nimport path from 'node:path';\nimport fs from 'node:fs';\n\nexport const config = {\n    // Customize your registry settings, if needed\n    registrySettings: { token: process.env.NPM_TOKEN },\n\n    // Common settings shared among packages\n    commonPackageSettings: {\n        sourcesFolder: path.join(process.cwd(), 'dist/'),\n        mainPackageJson: fs.readFileSync('./package.json', { encoding: 'utf8' })\n    },\n\n    // Define your packages\n    packages: [\n        {\n            name: 'first-package',\n            entryPoints: [ { js: 'first.js' } ],\n        },\n        {\n            name: 'second-package',\n            entryPoints: [ { js: 'second.js' } ],\n            entryPoints: ,\n            bundleDependencies: ['first']\n        }\n    ]\n};\n```\n\n**Publishing:**\n\nExecute the following command from the root of your project, no worries it runs in dry-run mode by default:\n\n```\nnpx packtory publish\n```\n\nFor more details about the CLI application have a look at the [full documentation](./source/packages/command-line-interface/readme.md).\n\n## Concept\n\n### Bundling\n\nPacktory guarantees minimal packages with:\n\n-   No published `devDependencies`\n-   No unnecessary files, including CI configurations\n\n**How Bundling Works:**\n\n1. All source files referenced from the entry point files are resolved into a graph.\n2. Imports of `node_modules` and node built-ins are detected and tracked to create a minimal `package.json` later.\n3. If bundle dependencies are given, some import statements will be rewritten. For example, if a file in package `first` imports a file in package `second`, the import statement will be rewritten accordingly (e.g., from `import bar from './bar.js'` to `import bar from 'second/bar.js'`).\n4. A `package.json` will be generated, and the version numbers of `node_modules` will be taken from the `mainPackageJson` provided in the configuration.\n\n### Publishing\n\n**How Publishing Works:**\n\nPacktory supports two versioning modes:\n\n1. **Automatic Versioning (Default) 🔄:**\n\n    - Fetch the version details of the latest information available from the registry.\n    - Download and extract the tarball of the latest version in-memory.\n    - Compare the contents of all files from the downloaded tarball with the contents of all files resolved from the bundler:\n        - If all files are the same, no new version is needed.\n        - If there are any differences, increase the latest version number by one (patch version), generate a new `package.json`, create a tarball, and publish the new version.\n    - If no version is available in the registry, an initial version will be built and published with version `0.0.1` (default but can be changed in the configuration).\n\n2. **Manual Versioning:**\n    - Provide the exact version number in the configuration.\n\nThis explanation provides a comprehensive overview of the bundling and publishing processes in Packtory. Feel free to make any further adjustments or let me know if there's anything specific you'd like to emphasize.\n\n## Configuration\n\nThe configuration for `packtory` is an object with the following properties:\n\n1. **`registrySettings`** (Required):\n\n    - An object with at least a required `token` for authentication.\n    - Optionally, you can provide a custom `registryUrl` for non-default registries.\n\n2. **`commonPackageSettings`** (Optional):\n\n    - Defines settings that can be shared for all packages.\n    - Allowed settings: `sourcesFolder`, `mainPackageJson`, `includeSourceMapFiles`, `additionalFiles`, `additionalPackageJsonAttributes`.\n\n3. **`packages`** (Required, Array):\n\n    - An array of per-package configurations.\n    - Each per-package configuration has the following settings:\n\n    - **`name`** (Required, String):\n\n        - Must be unique; the name of the package.\n\n    - **`sourcesFolder`** (Required):\n\n        - The absolute path to the base folder of the source files.\n        - All other file paths are resolved relative to this path.\n\n    - **`mainPackageJson`** (Required):\n\n        - The parsed content of the project's `package.json`.\n        - Needed to obtain version numbers of third-party dependencies.\n\n    - **`entryPoints`** (Required, Array of Objects):\n\n        - An array of entry points with the following shape: `{ js: 'file.js', declarationFile: 'file.d.ts' }`.\n        - The `js` property is required, while `declarationFile` is optional.\n\n    - **`includeSourceMapFiles`** (Optional, Boolean, Default: `false`):\n\n        - If `true`, the bundler will look for and include source map files in the final package.\n\n    - **`additionalFiles`** (Optional, Array of File Descriptions):\n\n        - An array to add additional files to the package that are not automatically resolved.\n        - Example: `{ sourceFilePath: 'LICENSE', targetFilePath: 'LICENSE' }`.\n        - If defined in both per-package and common settings, they are merged.\n\n    - **`additionalPackageJsonAttributes`** (Optional, Object):\n\n        - An object to be merged directly into the generated `package.json`.\n        - Useful for setting meta properties like `description` or `keywords`.\n        - If defined in both per-package and common settings, they are merged.\n\n    - **`bundleDependencies`** (Optional, Array of Strings):\n\n        - An array of package names to mark as dependencies, allowing the bundler to substitute import statements accordingly.\n\n    - **`bundlePeerDependencies`** (Optional, Array of Strings):\n        - Similar to `bundleDependencies` but represented as `peerDependencies` in the generated `package.json`.\n\n**Note**: Per-package settings override or merge with common settings when both are defined.\n\nThis comprehensive configuration allows fine-tuning for individual packages and provides flexibility in defining dependencies and additional files.\n\n## Example Use-Cases\n\n### 1. Creating CLI Tools\n\nSuppose you have a project with a utility library (`image-resizer-lib`) and a corresponding CLI tool (`image-resizer-cli`) with bin entry points. `packtory` simplifies the bundling and publishing of these packages while ensuring clean and minimal npm packages.\n\n```javascript\n// packtory.config.js\nexport const config = {\n    registrySettings: { token: process.env.NPM_TOKEN },\n    commonPackageSettings: {\n        sourcesFolder: path.join(process.cwd(), 'dist/'),\n        mainPackageJson: fs.readFileSync('./package.json', { encoding: 'utf8' })\n    },\n    packages: [\n        {\n            name: 'image-resizer-lib',\n            entryPoints: [{ js: 'lib.js' }]\n        },\n        {\n            name: 'image-resizer-cli',\n            entryPoints: [{ js: 'cli.js' }],\n            bundleDependencies: ['image-resizer-lib']\n        }\n    ]\n};\n```\n\n### 2. Managing Complex Dependencies\n\nConsider a scenario where you have an ecosystem of packages like `awesome-logger`, `awesome-logger-adapter`, and `awesome-logger-adapter-awesome-target`. `packtory` simplifies the bundling and publishing process, automatically managing dependencies between these packages.\n\n```javascript\n// packtory.config.js\nexport const config = {\n    registrySettings: { token: process.env.NPM_TOKEN },\n    commonPackageSettings: {\n        sourcesFolder: path.join(process.cwd(), 'src/'),\n        mainPackageJson: fs.readFileSync('./package.json', { encoding: 'utf8' })\n    },\n    packages: [\n        {\n            name: 'awesome-logger',\n            entryPoints: [{ js: 'index.js' }]\n        },\n        {\n            name: 'awesome-logger-adapter',\n            entryPoints: [{ js: 'adapter.js' }],\n            bundleDependencies: ['awesome-logger']\n        },\n        {\n            name: 'awesome-logger-adapter-awesome-target',\n            entryPoints: [{ js: 'target.js' }],\n            bundleDependencies: ['awesome-logger', 'awesome-logger-adapter']\n        }\n    ]\n};\n```\n\nThese examples demonstrate how `packtory` adapts to different project structures and facilitates the efficient bundling and publishing of packages with varying dependencies.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenormora%2Fpacktory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenormora%2Fpacktory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenormora%2Fpacktory/lists"}