Kickin - bootstrap your Eleventy project

We always chase productivity on our pages. And Web development community has got many instruments that help achieve this goal. Eleventy is one of them. It is a great tool that offers an easy way of combining templates and data into fully operative static pages that you can host on a server.

Unfortunately, it can bundle only templates and doesn't care about assets on the site, such as images, styles and scripts etc. So we decided to create a bundler based on Eleventy CLI 🤖 It isn't separate, but we use Eleventy's events for integration.

The primary tool is Kickin CLI. It quickly bootstraps a template folder with Eleventy and necessary plugins for comfortable development. Some of them were built by ourselves:

1. eleventy-plugin-compress
2. eleventy-plugin-pwa-icons
3. eleventy-plugin-scripts
4. eleventy-plugin-styles
5. eleventy-plugin-workbox
6. eleventy-shortcode-image

We don't recommend installing CLI globally. Instead, use a npx for project initialization.

The minimal required version of NodeJS is 12.17.0. The reason is that Kickin CLI consists of ES modules.

It exposes command that is named after itself - <mark>kickin</mark>. And its use is pretty simple.

npx kickin name-of-your-project

If you already have such a folder, you can use the . symbol instead of the name.

cd my-project-name
npx kickin .

Wait until the installation of dependencies completes, and that's all 🤗

After

There are four main commands available in the created project:

• <mark>npm start</mark> - starts development server on <mark>http://localhost:3000</mark>

• <mark>npm run build</mark> - builds project.

• <mark>npm run serve </mark>- runs a local server with secure protocol on <mark>https://localhost:3000</mark>. It helps to mimic the production environment.

• <mark>npm run certs</mark> - creates certificates for the ability to run site with HTTPS locally.

We use mkcert to generate SSL certificates. Make sure you installed it on your local machine as well.

You can change any part of the generated project as you want - configuration file and all dependencies are open to being changed.

Let's explore a little bit of what and where CLI installs.

Structure

• Source code is located in the <mark>src</mark> folder.
• <mark>assets</mark>: this folder supposed to be home for static content: images, fonts, video, audio etc.
• images

• fonts
• video
• audio
• <mark>components </mark>- folder where Eleventy's components are located (default name is <mark>_includes</mark>)

• <mark>layouts</mark> - folder for layouts .

• <mark>pages</mark> - place where future site's pages live.

• <mark>scripts</mark> - folder for scripts that will be used in HTML.

• <mark>styles</mark> - folder for styles.

• For bundled code, the <mark>build</mark> folder is preserved.

Inner structure of defined directories is up to you 🙃

Let's dig into plugins a little bit. There are 6 of them.

eleventy-plugin-compress

This plugin is used to compress <mark>HTML</mark>, <mark>CSS</mark> and <mark>JS</mark> using <mark>brotli</mark>(default, gzip or deflate algorithms. It helps you reduce the size of files that are sent over the internet.

Why brotli?

eleventy-plugin-pwa-icons

If you want to create PWA, you will need icons for your application for different platforms. This package uses pwa-assets-generator to create icons from an image. It will automatically insert links to icons into the HTML of every page and in the <mark>manifest.json</mark> file along with generated icons. All you need is an image as a template for future icons. By default, it is a <mark>favicon.png</mark> under the <mark>src</mark> directory.

eleventy-plugin-scripts

Starter supports modern JavaScript syntax (except for Eleventy's templates) and TypeScript.

All scripts files should be in the <mark>scripts/</mark> directory, but the inner structure does not matter.

To include scripts into an HTML page, provide <mark>scripts</mark> property in page template's front matter zone (can be either type of string or array of strings). The path to the script is relative to <mark>src/scripts</mark> directory, so you do not need to include this prefix in the URI.

// For JavaScript templates 
module.exports.data = { 
  // This will be resolved to 'src/scripts/main.js' 
  scripts: 'main.js', // or 'main.ts' -> 'src/scripts/main.ts' 
};

eleventy-plugin-styles

The configuration of this one is very similar to <mark>eleventy-plugin-scripts</mark>.

In Kickin Sass language is supported.

Stylesheets should be in <mark>styles/</mark> directory, but the inner structure does not matter. They will be compiled, minified and cleaned from unused selectors automatically.

To include style to page in the template, provide <mark>styles</mark> property in front matter zone. It can be string or array of strings. The path to the stylesheet is relative to <mark>src/styles</mark> directory, so you do not need to include this prefix in the URI.

// For JavaScript templates
module.exports.data = { 
  // Bundler of this starter is smart enough to recognize type of style 
  // and its location (file will be resolved to `src/styles/home.scss`)
  styles: 'home.scss',
};

If you want to put your CSS file in the inner folder, say <mark>directory/common.scss<mark>, don't forget to mention it in your config:

// For JavaScript templates
module.exports.data = { 
  styles: 'directory/common.scss', // -> src/styles/directory/common.scss
};

It is the most potent package of all! Whew... Amazing!

eleventy-plugin-workbox

Adds the Service worker that will automatically cache all assets of your site on a client.

Registration of service worker script will be automatically injected into each HTML page.

By default, the worker will cache static resources (images, fonts, audio files etc.) and try to use them from the cache at first. Dynamic resources that can be changed often (HTML, JS, CSS) are cached also, but on every request, it will try to fetch it on the server at first.

You can read more about strategies here.

eleventy-shortcode-image

It handles images of your page. It can properly rebase, minify and generate optimal types of images that all browsers support. It uses @11ty/eleventy-img under the hood but also can minify SVGs (uses SVGO). Compression is disabled in development mode to reduce build time. You want a quick response on your changes, aren't you? 😊 So, we do too.

For this purpose, the CLI includes an <mark>image</mark> shortcode. Use it to incorporate images to HTML (either raster or vector(SVG) ones).

Info about shortcodes and how to use them is here.

Signature of shortcode:

interface ImageAttributes {
  /** Defines alternative text for image. */
  alt?: string;
  /** Defines title for image. */
  title?: string;
  /** Class name(s) for `class` attribute. */
  classes?: string | ReadonlyArray<string>;
}

async function image(src: string, attributes?: ImageAttributes): Promise<string>;

The first parameter is mandatory and contains an image path relative to the <mark>src/assets/images directory</mark>.

// For JavaScript templates
module.exports.render = async function () {
  return /* html */ `<main>${await this.image('logo.png')}</main>`;
};

For example, logo.png image will be resolved to <mark>src/assets/images/logo.png</mark>, then <mark>webp</mark> and <mark>avif</mark> images will be generated and placed along with the source image in the <mark>build</mark> directory. In HTML, you will receive efficient images with the correct paths 😊!

The same rules apply if you define a path to the image from CSS (for example, in the URL function). But if you specify <mark>URL</mark> as absolute (absolute public URL), it will be returned as-is without any changes.

This is done intentionally in case if you want to copy assets to the output directory.

All these packages are attached to transform flow of Eleventy.

Configuration

The default configuration of Eleventy is enough for most use cases, but sometimes there you need to change some behaviour.

.eleventy.js is a starting point for Eleventy.

If you want to change some behaviour or add new feature to site, place it in <mark>.eleventy/</mark> directory. It has following structure:

• <mark>filters</mark> - used for holding custom filters.

• <mark>plugins</mark> - contains custom plugins for Eleventy.

• <mark>shortcodes</mark> - contains shortcodes.

• <mark>transforms</mark> - holds HTML transformer functions that changes generated HMTL by Eleventy.

Feel free to try it and give us feedback. We fell in love with these tools, and we hope you will too 🖤

Useful links:

This is a repository where a code of all plugins live.