eleventy-plugin-scripts 📜

⚠️ This code moves to the new location. Please, refer there to get a new development status.

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