eleventy-plugin-scripts

eleventy-plugin-scripts 📜

Bundles scripts of your site 💪

Intention

It is not convenient to use a third-party tools like gulp, webpack or whatever you know for processing scripts. Yeah 🤨... But why not to intergate this process with Eleventy? Sounds cool, right 😋!

Get started

What this plugin can do:

1. Fast bundling your JavaScript or TypeScript files. Thank you esbuild!
2. Setting correct relative paths between HTML and bundled JavaScript.

Installation

At first do:

npm i -D eleventy-plugin-scripts

and then you can include it into .eleventy.js:

const { scripts } = require('eleventy-plugin-scripts');

module.exports = (eleventyConfig) => {
	eleventyConfig.addPlugin(scripts, {
		/* Optional options. */
	});
};

Options

Plugin can accept the following options:

interface ScriptsPluginOptions {
	/**
	 * Path to directory with all scripts
	 * Should be relative to _current working directory_.
	 */
	inputDirectory?: string;
	/**
	 * Directory inside _output_ folder to be used as
	 * warehouse for all compiled scripts. Will be
	 * prepended to public script urls in HTML.
	 */
	publicDirectory?: string;
	/**
	 * Options that can be passed to [`esbuild`](https://esbuild.github.io).
	 */
	esbuildOptions?: BuildOptions;
	/**
	 * Indicates whether should Eleventy watch on files
	 * under _inputDirectory_ or not.
	 */
	addWatchTarget?: boolean;
}

Explanation

inputDirectory

Plugin extracts URLs to script files from HTML. Therefore your templates should have links to source script files.

For example:

<!-- Note that we wrote `main.ts` 👇 -->
<script type="module" src="main.ts"></script>

Plugin recognizes followed extensions: js and ts. In future may be added much more if you will need it 🤓

After URL extraction plugin will search for these files inside inputDirectory from options. So given above example:

// .eleventy.js
module.exports = (eleventyConfig) => {
	eleventyConfig.addPlugin(scripts, {
		// This is a default value
		inputDirectory: 'src/scripts',
	});
};

Plugin will assume that path of script file is src/scripts/main.ts 🎉 And after all procedures will put compiled file to _site/main.js and URL in HTML will be changed to:

<!-- If HTML file is in the same directory if main.js -->
<script type="module" src="main.js"></script>

_site is used just for example. Actually name of the directory will be up to you - plugin will know about it.

If HTML file is in other directory, then referenced script file, plugin will build relative path to it. For example, if output of HTML is _site/pages/about/index.html and script's public path is main.js(in root of _site), then plugin formats public path to ../../main.js. So you aren't needed to fix URLs to your assets 🤘!

publicDirectory

If you want to customize output path of compiled script inside output directory, then you can provide publicDirectory option.

// .eleventy.js
module.exports = (eleventyConfig) => {
	eleventyConfig.addPlugin(scripts, {
		inputDirectory: 'src/scripts',
		publicDirectory: 'scripts',
	});
};

Given above example, script file will be placed into _site/scripts directory and it's public path will be scripts/main.js.

Pretty convenient, yes? 🙂

addWatchTarget

By default Eleventy will watch for changes inside inputDirectory. You have an opportunity to disable it:

// .eleventy.js
module.exports = (eleventyConfig) => {
	eleventyConfig.addPlugin(scripts, {
		// Now Eleventy will not trigger rebuild process
		// if any script changes.
		addWatchTarget: false,
	});
};

esbuildOptions

Internally for bundling scripts is responsible esbuild. It bundles each script with all dependencies, that you will reference from templates, into one [ES2018]-compliant file.

You customize its behavior by providing build options.

// .eleventy.js
module.exports = (eleventyConfig) => {
	eleventyConfig.addPlugin(scripts, {
		esbuildOptions: {
			/* Some useful options. */
		},
	});
};

Avoid changing entryPoints and outfile properties, because in HTML may be passed wrong script URL.

Word from author

Have fun! ✌️