1.1.6 • Public • Published

eleventy-plugin-scripts 📜

code style: prettier

Bundles scripts of your site 💪


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.


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. */


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;



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 🤘!


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? 🙂


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,


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! ✌️

Developed in Halo lab

Package Sidebar


npm i eleventy-plugin-scripts

Weekly Downloads






Unpacked Size

31.5 kB

Total Files


Last publish


  • halolab