\n\nNews Fragments is a plugin for [release-it](https://github.com/release-it/release-it) that generates a changelog from small \"fragment\" files. During development, contributors add one fragment file per change; at release time the fragments are compiled into a versioned changelog entry and then deleted automatically.\n\n## Requirements\n\n- Node v22+\n- npm v10+\n\n## Installation\n\n```bash\nnpm install news-fragments\n```\n\n## Setup\n\nAdd `news-fragments` as a plugin inside your [release-it](https://github.com/release-it/release-it) configuration in `package.json`:\n\n```json\n{\n \"release-it\": {\n \"plugins\": {\n \"news-fragments\": {}\n }\n }\n}\n```\n\nPass any [config options](#config-params) directly in this object to override the defaults.\n\n---\n\n## Release Workflow\n\nFollow these steps every time you need to publish a new version.\n\n### 1. Create fragment files during development\n\nFor each change you want to appear in the changelog, run:\n\n```bash\nnews-fragments create \"\"\n```\n\n**Available fragment types** (default): `feature`, `bugfix`, `doc`, `removal`, `misc`.\n\nExamples:\n\n```bash\nnews-fragments create feature \"Add dark mode support\"\nnews-fragments create bugfix \"Fix race condition on login\"\nnews-fragments create misc \"Update dependencies\"\n```\n\nEach command creates a timestamped file inside the `fragments/` folder (e.g., `fragments/1714220400000.feature`). Commit these files together with the code changes they describe.\n\n### 2. Preview the next changelog entry\n\nBefore releasing, verify what the generated changelog will look like:\n\n```bash\nnews-fragments preview\n```\n\nTo preview an already-released version stored in `CHANGELOG.md`:\n\n```bash\nnews-fragments preview -p \n# e.g. news-fragments preview -p 1.2.3\n```\n\n### 3. Run the release\n\n```bash\nnpm run release\n```\n\nThis command triggers `release-it`, which will:\n\n1. Run the test suite (`npm test`) as a pre-release check.\n2. Prompt you to select the next version (patch / minor / major).\n3. Burn the pending fragments into `CHANGELOG.md` under the new version header and delete the fragment files.\n4. Bump the version in `package.json`.\n5. Commit, tag, and push the release.\n\n> The burn step runs automatically via the `news-fragments` plugin — you do **not** need to run `news-fragments burn` manually when using `release-it`.\n\n### Manual burn (without release-it)\n\nIf you need to compile fragments into the changelog outside of `release-it`, use:\n\n```bash\nnews-fragments burn \n# e.g. news-fragments burn 2.0.0\n```\n\nThis writes the changelog entry for `` and removes all consumed fragment files.\n\n---\n\n## Config\n\n### Default config\n\n```json\n{\n \"changelogFile\": \"CHANGELOG.md\",\n \"changelogDateFormat\": \"YYYY-MM-DD\",\n \"changelogTemplate\": \"\",\n \"fragmentsFolder\": \"fragments\",\n \"fragmentsTypes\": [\n { \"title\": \"Features\", \"extension\": \"feature\" },\n { \"title\": \"Bugfixes\", \"extension\": \"bugfix\" },\n { \"title\": \"Documentation\", \"extension\": \"doc\" },\n { \"title\": \"Deprecations and Removals\", \"extension\": \"removal\" },\n { \"title\": \"Misc\", \"extension\": \"misc\" }\n ]\n}\n```\n\n### Default changelog template\n\n```handlebars\n# [{{newVersion}}] - ({{bumpDate}})\n{{#fragments}}\n## {{title}}\n{{#each fragmentEntries}}\n* {{this}}\n{{/each}}\n{{/fragments}}\n```\n\n### Config params\n\n| Key | Description |\n|-----|-------------|\n| `changelogFile` | Path to the changelog file. |\n| `changelogDateFormat` | [Moment.js](https://momentjs.com/docs/#/displaying/format/) date format used in the changelog header. |\n| `changelogTemplate` | A [Handlebars](https://handlebarsjs.com/) template string for each version block. |\n| `fragmentsFolder` | Path to the folder where fragment files are stored. |\n| `fragmentsTypes` | Array of `{ title, extension }` objects that define the supported fragment types and their changelog section headings. |\n\n> See this plugin in action by checking our [CHANGELOG.md](./CHANGELOG.md)\n\n---\n\n## CLI Reference\n\n```bash\nnews-fragments --help\n```\n\n| Command | Description |\n|---------|-------------|\n| `news-fragments create \"\"` | Create a new fragment file of the given type. |\n| `news-fragments preview` | Print the next changelog entry to the terminal. |\n| `news-fragments preview -p ` | Print a previously released changelog entry. |\n| `news-fragments burn ` | Compile fragments into the changelog and delete them. |\n\n---\n\n## Contributing\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests (includes lint)\nnpm test\n```\n","readmeFilename":"README.md"}
![\"Logo\"](\"./changelog.png\" "\\"Logo\\"")
\n![\"npm](\"https://img.shields.io/npm/v/news-fragments?label=version&color=blue\")
![\"weekly](\"https://img.shields.io/npm/dw/news-fragments?color=green\")
![\"license\"](\"https://img.shields.io/npm/l/news-fragments\")