A Parcel plugin that lets you customize your output (dist) directory folder structure.
If you โค๏ธ this plugin and want to support, you can buy me a coffee!
When building for production, Parcel outputs the build in a flat structure. In some cases, we might need a particular structure for the built output.
This plugin lets you organize every file output by Parcel by matching and moving assets into your desired structure. It also updates all references in every file to ensure that the output is ready for consumption with your custom structure.
Advantages of using the plugin:
- Supports excellent and fine-grained configuration for all use cases out of the box using glob pattern matching
- Super fast and rapid restructuring means you do not need to worry about a massive overload in build times.
- Respects
publicUrlpassed to Parcel bundler while restructuring the folder. - Respects the
outDirpassed to Parcel bundler and only restructures files within. - Sensible defaults to get you up and running quickly.
Installation is straight forward using NPM or Yarn:
# Using NPM
npm install --save-dev parcel-plugin-structurize
# Using Yarn
yarn add -D parcel-plugin-structurizeMigrating from v1 to v2 of the plugin is super simple.
In your project, first upgrade the plugin:
yarn upgrade [email protected]
Then upgrade the configuration in package.json:
# package.json file
{
"parcel-plugin-structurize": {
- "scripts": {
- "match": "*.{js,js.map}",
- "folder": "js"
- },
- "styles": {
- "match": "*.{css,css.map}",
- "folder": "css"
- },
- "assets": {
- "match": "*.{png,svg,jpg,jpg2,jpeg,gif,bmp,webm}",
- "folder": "assets"
- }
+ "rules": [
+ {
+ "match": "*.js",
+ "folder": "js",
+ },
+ {
+ "match": "*.css",
+ "folder": "css",
+ },
+ {
+ "match": "*.{png,svg,jpg,jpg2,jpeg,gif,bmp,webm}",
+ "folder": "assets",
+ },
+ ],
}
}There are two ways to configure the plugin:
- Adding the
parcel-plugin-structurizekey topackage.json.
// package.json
{
"parcel-plugin-structurize": {
"rules": [
{
"match": "*.js",
"folder": "scripts"
},
{
"match": "*.{jpg,png,gif,svg}",
"folder": "images"
}
]
}
}- Via a
parcel-plugin-structurize.jsonfile in your project root (right next to yourpackage.json).
// parcel-plugin-structurize.json
{
"rules": [
{
"match": "*.js",
"folder": "scripts"
},
{
"match": "*.{jpg,png,gif,svg}",
"folder": "images"
}
]
}Note: This plugin runs ONLY in
parcel buildor whenNODE_ENV=production, since the use-case of running it inwatch,serveorNODE_ENV=developmentis not compelling enough.
The plugin allows for fine-grained configuration options to ensure proper customization of the output directory.
The configuration includes the following options:
-
StructurizerAn array of objects which are called Structurizers.
-
booleanWhether to enable verbose logging or not.
-
booleanWhether to display the generated assets map or not. This only comes into effect if
verboseistrue.
You can disable the plugin by two means:
- Set
rulesattribute in your config tofalse. - Set environment variable
PARCEL_PLUGIN_STRUCTURIZEtofalse. Ex:
PARCEL_PLUGIN_STRUCTURIZE=false parcel build src/index.htmlStructurizer is a rule that contains match patterns and the target.
type Config = {
match: string;
folder: string;
flatten?: boolean;
};-
stringA glob pattern to match file names and group them to a folder.
-
stringThe folder to place the files in. Can contain nested folders (ex:
scripts/vendors,images/vectors/user/avatar) -
booleanFor nested files, whether to flatten them to the output folder or not.
You can provide as many Structurizers in your configuration file. The plugin ships with sensible defaults.
// default config
{
"verbose": false,
"rules": [
{
"match": "*.js",
"folder": "js",
"flatten": false
},
{
"match": "*.css",
"folder": "css",
"flatten": false
},
{
"match": "*.{jpg,jpeg,jpeg2,png,gif,svg,bmp,webp}",
"folder": "assets",
"flatten": false
}
]
}-
The order of the Structurizers matter if you want to target a glob and a file ending with the same extension. To better illustrate this, let's consider the following files in your output directory:
index.htmlcontact.htmlabout.html
If you want to move all HTML files into a folder called
app, except theindex.htmlthen you need to keep in mind the order of the Structurizers.
# The following will produce the desired results
+ Correct
[
{
"match": "index.html",
"folder": "."
},
{
"match": "*.html",
"folder": "app"
}
]
# And the following will result in your `index.html` to be placed inside the `app` directory as well
- Incorrect
[
{
"match": "*.html",
"folder": "app"
},
{
"match": "index.html",
"folder": "."
}
]- You should NOT add any structurizer rules for
.mapfiles as the plugin automatically resolves and restructures the sourcemap files to reside in the same directory as its parent. This can cause unintended side-effects.
To get the project up and running, clone it and then run the following command:
yarn bootstrapIt will install all packages, link dependencies and set everything up. To start the dev server:
yarn devTo build the bundle, simply run:
yarn buildBundles watch for changes to the plugin and rebuild with Parcel bundler, causing the plugin to trigger. Once you have the plugin running in dev mode, you can run the following command for the bundles:
(cd __tests__/bundle && yarn dev)To test you can run:
yarn test:watchPlease report any bugs here. For any questions feel free to create an issue.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
