{"id":19407582,"url":"https://github.com/kitschpatrol/eleventy-plugin-parcel","last_synced_at":"2025-06-17T21:43:51.778Z","repository":{"id":59442446,"uuid":"536436491","full_name":"kitschpatrol/eleventy-plugin-parcel","owner":"kitschpatrol","description":"A plugin integrating the Parcel build tool and dev server with the Eleventy static site generator.","archived":false,"fork":false,"pushed_at":"2025-03-04T06:57:35.000Z","size":290,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-22T00:08:32.800Z","etag":null,"topics":["eleventy","eleventy-plugin","npm-package","parcel"],"latest_commit_sha":null,"homepage":"https://github.com/kitschpatrol/eleventy-plugin-parcel","language":"JavaScript","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/kitschpatrol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-09-14T06:06:22.000Z","updated_at":"2025-03-04T06:57:54.000Z","dependencies_parsed_at":"2024-05-03T16:03:48.117Z","dependency_job_id":"84754ed5-eae0-4bd3-bc79-e281c7843c76","html_url":"https://github.com/kitschpatrol/eleventy-plugin-parcel","commit_stats":{"total_commits":6,"total_committers":1,"mean_commits":6.0,"dds":0.0,"last_synced_commit":"664e5a30b6e8478c4ed33c89a83b98b9620c6a07"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Feleventy-plugin-parcel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Feleventy-plugin-parcel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Feleventy-plugin-parcel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Feleventy-plugin-parcel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitschpatrol","download_url":"https://codeload.github.com/kitschpatrol/eleventy-plugin-parcel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250600709,"owners_count":21457012,"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":["eleventy","eleventy-plugin","npm-package","parcel"],"created_at":"2024-11-10T12:03:03.676Z","updated_at":"2025-04-24T09:31:38.289Z","avatar_url":"https://github.com/kitschpatrol.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--+ Warning: Content inside HTML comment blocks was generated by mdat and may be overwritten. +--\u003e\n\n\u003c!-- title --\u003e\n\n# @kitschpatrol/eleventy-plugin-parcel\n\n\u003c!-- /title --\u003e\n\n\u003c!-- badges --\u003e\n\n[![NPM Package @kitschpatrol/eleventy-plugin-parcel](https://img.shields.io/npm/v/@kitschpatrol/eleventy-plugin-parcel.svg)](https://npmjs.com/package/@kitschpatrol/eleventy-plugin-parcel)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003c!-- /badges --\u003e\n\n\u003c!-- short-description --\u003e\n\n**A plugin integrating the Parcel build tool and dev server with the Eleventy static site generator.**\n\n\u003c!-- /short-description --\u003e\n\n## Overview\n\nThis plugin adds a [Parcel](https://parceljs.org) bundling step to the [Eleventy](https://www.11ty.dev) build process, and (optionally) allows the use of the Parcel Development Server as middleware during development.\n\nParcel is invoked automatically each time Eleventy finishes a build of your site, performing additional optimization and transpilation of various scripts and resources. Eleventy then launches its integrated development server to provide a preview of the site with automatic reloading when files are changed.\n\nThis post-processing step happens entirely within Eleventy's plugin system; no additions or modifications to your NPM scripts are required.\n\n## Getting started\n\n### Dependencies\n\nThis plugin is designed for Eleventy 2.x and Parcel 2.x. It is _not_ compatible with Eleventy 1.x. It has not yet been tested with Eleventy 3.x. Node 14+ is required.\n\nThe installation instrutions below assume you already have an Eleventy 2.x project that you want to add Parcel to.\n\n### Installation\n\n1. Add the plugin to your Eleventy project:\n\n   ```\n   $ npm install --save-dev @kitschpatrol/eleventy-plugin-parcel\n   ```\n\n2. Load the plugin in your `.eleventy.js` file:\n\n   ```js\n   const eleventyParcelPlugin = require(\"@kitschpatrol/eleventy-plugin-parcel\");\n\n   module.exports = function (eleventyConfig) {\n     eleventyConfig.addPlugin(eleventyParcelPlugin);\n   };\n   ```\n\n   Note that if you do _not_ want to use the Parcel Development Server as middleware when serving your site, pass the `useMiddleware: false` option when adding the plugin:\n\n   ```js\n   const eleventyParcelPlugin = require(\"@kitschpatrol/eleventy-plugin-parcel\");\n\n   module.exports = function (eleventyConfig) {\n     eleventyConfig.addPlugin(eleventyParcelPlugin, { useMiddleware: false });\n   };\n   ```\n\n   This serves your site as usual via an unmodified version of the Eleventy Dev Server, but Parcel will still process your output.\n\n3. Create a [`.parcelrc`](https://github.com/parcel-bundler/parcel/blob/65500fbb07ff100c1fe5dd32e98fb80ff889f32e/packages/core/types/index.js#L55) file in your project's root including at least the following:\n\n   ```json\n   {\n     \"extends\": \"@parcel/config-default\",\n     \"resolvers\": [\"@mischnic/parcel-resolver-root\", \"...\"]\n   }\n   ```\n\n   _You must include this for absolute links to resolve correctly in the `output` subfolder when Parcel spiders through your site!_\n\n## Usage\n\nBuild and run your Eleventy project as usual. The output from Eleventy will be passed to Parcel, which will process the site, replacing the contents of your `output` folder (usually `_site`), and then start the Eleventy Dev Server:\n\n```\n$ npx @11ty/eleventy --serve --quiet\n```\n\nA normal Eleventy build will output your site with all Parcel optimizations enabled:\n\n```\n$ npx @11ty/eleventy\n```\n\n## Configuration\n\nAdditional configuration may be passed to Parcel when the plugin is added to Eleventy's configuration.\n\nThe available top-level option keys are as follows:\n\n- `parcelOptions`\n\n  Object passed to configure additional options as specified by Parcel's [InitialParcelOptions type](https://parceljs.org/plugin-system/api/#InitialParcelOptions).\n\n  Defaults to:\n\n  ```js\n  {\n    parcelOptions: {\n      entries: \"index.html\",\n      defaultConfig: \"@parcel/config-default\",\n      shouldDisableCache: true,\n      shouldAutoInstall: true,\n      serveOptions: {\n        port: 3000,\n      },\n      hmrOptions: {\n        port: 3001,\n      }\n    }\n  }\n  ```\n\n  _Important notes about how the plugin dynamically modifies the `parcelOptions` object in an effort to make your life more convenient:_\n\n  By default, Parcel's `mode` option is set dynamically based on the context of the build. Serve builds, e.g. `npx @11ty/eleventy --serve`, gets `\"development\"` mode, while release builds, e.g. `npx @11ty/eleventy` gets `\"production\"`. You can override this by passing an explicit `mode` string to your `parcelOptions`.\n\n  The Plugin automatically uses your Eleventy project's `output` folder to correctly prefix your `parcelOptions.entries` string or array.\n\n  Similarly, for release builds, Parcel's `defaultTargetOptions.distDir` path is automatically set to match Eleventy's `output`.\n\n- `tempFolderName`\n\n  String with name of folder to stage the Parcel builds. Defaults to `.11ty-parcel-temp` There's little reason to change this unless there is a conflict. This folder is automatically created and cleaned up during the release build process, but may linger during a `serve` build. It's recommended to add this path, along with `.parcel-cache` to you `.gitignore`.\n\n- `useMiddleware`\n\n  Boolean specifying whether to use the Parcel development server as middleware. Defaults to `true`.\n\n- `middlewareOptions`\n\n  Object passed to the middleware (if `useMiddleware: true`) as specified by the [http-proxy-middleware options type](https://github.com/chimurai/http-proxy-middleware#options).\n\nParcel will also pull configuration from a [`.parcelrc`](https://github.com/parcel-bundler/parcel/blob/65500fbb07ff100c1fe5dd32e98fb80ff889f32e/packages/core/types/index.js#L55) file in your project's root to further customize the build process.\n\n### Examples\n\nHere are a few example configurations to customize the Parcel's plugin's behavior. These object are passed to the plugin via the `addPlugin` method, usually in your projects `.eleventy.js` file.\n\n#### Skip middleware\n\nSkip the Parcel middleware and always build with all Parcel's optimizations enabled, regardless of invocation context:\n\n```js\nconst eleventyParcelPlugin = require(\"@kitschpatrol/eleventy-plugin-parcel\");\n\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(eleventyParcelPlugin, {\n    parcelOptions: {\n      mode: \"production\",\n    },\n    useMiddleware: false,\n  });\n};\n```\n\n#### Custom rewrite\n\nCustomize settings passed to `http-proxy-middleware` to rewrite paths in a way that allows you to drop the `.html` from URLs. This works well with the [parcel-optimizer-friendly-urls Parcel plugin](https://github.com/vseventer/parcel-optimizer-friendly-urls).\n\n```js\nconst eleventyParcelPlugin = require(\"@kitschpatrol/eleventy-plugin-parcel\");\n\nmodule.exports = function (eleventyConfig) {\n  eleventyConfig.addPlugin(eleventyParcelPlugin, {\n    useMiddleware: true,\n    middlewareOptions: {\n      pathRewrite: {\n        \"^([^.]+?)$\": \"$1.html\",\n      },\n    },\n  });\n};\n```\n\n## Background\n\n### Motivation\n\nSimplicity and a sense of containment are part Eleventy's charm, and there's a certain appeal to keeping the build process as \"close to the core\" as possible, even as a site's complexity accumulates. The very thorough [eleventy-high-performance-blog](https://github.com/google/eleventy-high-performance-blog) starter template illustrates this philosophy in practice.\n\nFor a while I've hewn to a similar approach in my own projects, but have found myself plumbing together byzantine chains of smaller tools to optimize images, add cache-busting hashes, generate CSP headers, etc. etc. — problems that have been solved several times over by a variety of build tools.\n\nAn official asset pipeline has been [a topic of discussion on Eleventy's issue pages over the years](https://github.com/11ty/eleventy/issues/272). [Vite](https://vitejs.dev) seems likely to be ordained as such, but Parcel has significant feature overlap — so I wanted to kick the tires on it as well as a point of comparison.\n\n### Implementation notes\n\n- Passthrough files must be copied to the output folder to be accessible to Parcel (the plugin sets `eleventyConfig.setServerPassthroughCopyBehavior(\"copy\");`)\n- Not tested with Eleventy's [Serverless](https://www.11ty.dev/docs/plugins/serverless/) or [Edge](https://www.11ty.dev/docs/plugins/edge/) features\n- The dom-diffing [morphdom](https://github.com/patrick-steele-idem/morphdom) functionality integrated in the Eleventy Dev Server's auto-reloading logic does not play well with Parcel's output, and must be disabled (the plugin sets `eleventyConfig.setServerOptions({ domdiff: false });`)\n- Parcel's caching system seems to have issues with Eleventy's output, and is disabled via the `shouldDisableCache` option\n- Parcel is configured with `shouldAutoInstall` enabled by default, which means it will automatically make changes to your `package.json` as plugins are needed to handle various file types\n- To avoid duplication of certain configuration parameters, the plugin writes an object related to the [parcel-resolver-root](https://github.com/mischnic/parcel-resolver-root) Parcel plug-in default to your `package.json` if needed\n- Unlike Parcel 1.x, Parcel 2.x [does not bundle middleware functionality](https://github.com/parcel-bundler/parcel/discussions/4612) as part of its development server... Instead, the plugin establishes the middleware proxy via [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)\n\n### Similar projects\n\nMany others have combined Parcel and Eleventy in various ways and at different points in the build chain:\n\n- Michelle Barker's [eleventy-parcel](https://github.com/mbarker84/eleventy-parcel)\n- Rico Sta. Cruz's [eleventy-parcel-demo](https://github.com/rstacruz/eleventy-parcel-demo)\n- Mark van Seventer's [eleventy-parcel-boilerplate](https://github.com/vseventer/eleventy-parcel-boilerplate)\n- Chris D. Macrae's [parceleventy](https://github.com/chrisdmacrae/parceleventy)\n- Dusty Candland's [11ty-starter](https://github.com/candland/11ty-starter)\n\nAlso:\n\n- CloudSh [blog post](https://cloudsh.com/eleventy/posts/2019/eleventy_and_parceljs_working_together.html)\n\n## The future\n\n- [ ] Eleventy 3.x testing and support\n- [ ] Alternative to resolver dependency\n- [ ] Pass resolver plugin options differently to avoid dynamically modifying `package.js`\n- [ ] Support Parcel's cache (currently has issues with reloading)\n- [ ] Legacy BrowserSync dev server reload timing issues\n- [ ] More intelligent Parcel entry point than `index.html` to accommodate sites with un-crawlable pages\n\n## Maintainers\n\n[@kitschpatrol](https://github.com/kitschpatrol)\n\n## Acknowledgments\n\nThis plugin is basically a port of Zach Leat's [eleventy-plugin-vite](https://github.com/11ty/eleventy-plugin-vite) from Vite to Parcel.\n\n\u003c!-- footer --\u003e\n\n## Contributing\n\n[Issues](https://github.com/kitschpatrol/eleventy-plugin-parcel/issues) and pull requests are welcome.\n\n## License\n\n[MIT](license.txt) © Eric Mika\n\n\u003c!-- /footer --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Feleventy-plugin-parcel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitschpatrol%2Feleventy-plugin-parcel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Feleventy-plugin-parcel/lists"}