{"id":19579872,"url":"https://github.com/axa-ch/metalsmith-incremental","last_synced_at":"2025-04-27T08:32:00.484Z","repository":{"id":57295570,"uuid":"79117817","full_name":"axa-ch/metalsmith-incremental","owner":"axa-ch","description":"Faster incremental builds for MetalSmith","archived":true,"fork":false,"pushed_at":"2018-04-04T14:40:41.000Z","size":68,"stargazers_count":11,"open_issues_count":2,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-20T04:09:21.491Z","etag":null,"topics":["build-automation","build-pipelines","incremental","metalsmith","middleware","plugin"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axa-ch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-16T12:50:17.000Z","updated_at":"2025-02-04T13:56:35.000Z","dependencies_parsed_at":"2022-08-27T12:20:40.327Z","dependency_job_id":null,"html_url":"https://github.com/axa-ch/metalsmith-incremental","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axa-ch%2Fmetalsmith-incremental","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axa-ch%2Fmetalsmith-incremental/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axa-ch%2Fmetalsmith-incremental/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axa-ch%2Fmetalsmith-incremental/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axa-ch","download_url":"https://codeload.github.com/axa-ch/metalsmith-incremental/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251112545,"owners_count":21538162,"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":["build-automation","build-pipelines","incremental","metalsmith","middleware","plugin"],"created_at":"2024-11-11T07:19:26.989Z","updated_at":"2025-04-27T08:31:57.936Z","avatar_url":"https://github.com/axa-ch.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metalsmith-incremental\n\nFaster incremental builds for MetalSmith\n\n# Install\n\n````sh\nnpm i metalsmith-incremental\n````\n\n# Usage\n\n1. Find out which is the slow part of your build.\n**Hint:** Go and checkout [`metalsmith-timer`](https://www.npmjs.com/package/metalsmith-timer)\nThis will give you insights in your concrete bottleneck.\n\n2. Wrap your plugin middleware with `metalsmith-incremental`, like:\n\n  ````js\n  import metalsmith from 'metalsmith'\n  // import any plugins here\n  // ...\n  import incremental from 'metalsmith-incremental'\n\n  // filter unmodified files\n  metalsmith.use(incremental({ plugin: 'filter' }))\n  // run slow plugins\n  metalsmith.use(slowPlugin())\n  // restore unmodified files\n  metalsmith.use(incremental({ plugin: 'cache' }))\n\n  // optionally enable watching\n  if(process.env.NODE_ENV === 'development') {\n    metalsmith.use(incremental({ plugin: 'watch' }))\n  }\n\n  // in case you have restored all files with cache plugin\n  // call filter plugin as last middleware\n  metalsmith.use(incremental({ plugin: 'filter' }))\n\n  // build metalsmith\n  metalsmith.build((err) =\u003e {\n    if (err) throw err\n  })\n  ````\n\n3. In case your plugin wraps content which could include other content (dependencies), you can specify custom `RegExp` or `Function`, which should extract those depended files and occasionally rebuild them too (`.jade` and `.pug` is supported by default).\n\n  ````js\n  // dependencies with RegEx\n  metalsmith.use(incremental({\n    depResolver: /^import [\"'](.*)['\"]$/mg\n  }))\n  metalsmith.use(slowPlugin())\n  ````\n\n  **Important:** Your RegEx has to define one capturing group (which holds the dependency path data), match global and multiline.\n\n  ````js\n  // dependencies with Function\n  metalsmith.use(incremental({\n    depResolver: (file, baseDir) =\u003e {\n      const dependencies = []\n      // do your custom magic to find dependencies\n      return dependencies\n    }\n  }))\n  metalsmith.use(slowPlugin())\n  ````\n\n  **Note:** You can also pass a hash of `RegEx` or `Function` by file extension.\n\n4. Don't forget to enable file watching (if your are in dev mode)\n\n  ````js\n  // optionally enable watching\n  if(process.env.NODE_ENV === 'development') {\n    metalsmith.use(incremental({ plugin: 'watch' }))\n  }\n  ````\n\n5. Make sure to write only modified files to disk, by calling `filter` at the last middleware\n\n  ````js\n  metalsmith.use(incremental({ plugin: 'filter' }))\n  ````\n\n  **Important:** This plugin is designed to be used only with MetalSmith plugins who operate on file basis. Other plugins who depend on `metadata`, etc may break.\n\n# Edge Cases\n\nSpecial circumstances like dependencies, plugins renaming, deleting, adding files should be considered carefully.\n\n## Dependencies\n\nLet's consider you are using a template engine like `PugJS` and you are changing a `partial`, `mixin` or `extend`ed layout.\nThis means each file which includes those dependencies needs to be rebuild too, even if they did not change itself.\n\nTo solve these you have basically two methods to chose from:\n* [Dependency Resolver config for `filter` plugin](.API.md#dependencyresolver)\n* [Paths Map config for `watch` plugin](.API.md#pathsobject)\n\n**Note**\n\nThe `Paths-Map` makes especially sense if you remove some files by `metalsmith-branch` or `metalsmith-ignore` temporarily from the pipeline (which makes them unavailable for dependency resolver) but still want to trigger updates on other files if one of those ignored files has changed.\n\n**Dynamic Dependencies**\n\nIf you dynamically include dependencies then your best bet is again `Paths-Map` config, or your write your own very clever dependency resolver function.\n\n## Renaming\n\nIf you are using any plugin like `metalsmith-markdown` or any template engine like `PugJS` it's very likely that the original file extension changes from `.md` or `.pug` to `.html`.\n\nTo solve these just let the `cache` plugin know those renaming rules:\n* [Rename Object config for `cache` plugin](.API.md#renameobject)\n* [Rename Function config for `cache` plugin](.API.md#renamefunction)\n\n## Circular Dependencies and metadata\n\nWe recommend to always build metadata from scratch. But if you really have an intensive metadata plugin. You can force updates of file's metadata (not global metadata):\n* [Props List config for `cache` plugin](.API.md#propslist)\n\n## Trouble with `metalsmith-collections`?\n\nCheck https://github.com/segmentio/metalsmith-collections/issues/27\n\n# API\n\nCheck our [API documentation](./API.md).\n\n# Inspiration\nAfter we had very long metalsmith builds during development, it was time to seek for change.\nWe have found this inspiring blog post http://www.mograblog.com/2016/11/speed-up-metalsmith.html.\nThough it was far from complete, not mentioning circular references, dependencies, metadata and more very specific stuff, we decided to take the next step.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxa-ch%2Fmetalsmith-incremental","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxa-ch%2Fmetalsmith-incremental","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxa-ch%2Fmetalsmith-incremental/lists"}