factorial-io/eleventy-plugin-fstack

@factorial/stack for Eleventy

Eleventy + Factorial Stack

+

This package adds a simple build task to the Eleventy build pipeline via eleventy.before. Furthermore it cleans the build folder before every build due to the fact, that caching is currently not available within our @factorial-io/eleventy-plugin-twig templating plugin.

Getting Started

Clone the latest release into a separate folder in your existing eleventy installation and install via yarn:

mkdir plugins && cd plugins
git clone https://source.factorial.io/factorial/eleventy-plugin-fstack.git
cd eleventy-plugin-fstack && yarn install --frozen-lockfile

Then use yarn link inside the eleventy-plugin-fstack folder to generate a package link and attach that to your eleventy installation from inside your eleventy folder with yarn link "@factorial/eleventy-plugin-fstack". Now you can require("@factorial/eleventy-plugin-fstack") like below.

Please also add @factorial/stack-core and all necessary packages to your project dependencies via yarn:

yarn add @factorial/stack-core @factorial/stack-css ...

Usage

Config @factorial/fstack

First define a .factorialrc.js in your projects root folder. For details please check the @factorial/fstack repository.

Note: eleventy-plugin-fstack requires @factorial/stack to generate hashed css and js files. Please do not forget to set the addHashes: true option in .factorialrc.js.

Config eleventy-plugin-fstack

For Eleventy to recognize this you have to register this as a plugin. To do so modify the .eleventy.js config file:

const fstack = require("@factorial/eleventy-plugin-fstack");

module.exports = function(eleventyConfig) {
  ...
  eleventyConfig.addPlugin(fstack, USER_OPTIONS);
  ...
  return {
    dir: {
      input: USER_OPTIONS.dir.input,
      output: USER_OPTIONS.dir.output,
      includes: getIncludesFolderFromNamespaces(
        USER_OPTIONS.dir.input,
        USER_OPTIONS.twig.namespaces
      ),
      layouts: path.relative(
        path.join(process.cwd(), USER_OPTIONS.dir.input),
        path.join(__dirname, USER_OPTIONS.dir.layouts)
      ),
    },
  };
}

If you use the @factorial/eleventy-plugin-twig plugin you could utilize the TWIG_OPTIONS.namespaces here as well and use getIncludesFolderFromNamespaces(input, namespaces). This method you could copy from here:

/**
 * Uses the namespaces provided for twig to generate
 * a proper glob for eleventies include folder
 *
 * @param {USER_OPTIONS["dir"]["input"]} input
 * @param {USER_OPTIONS["twig"]["namespaces"]} namespaces
 * @returns {string}
 */
const getIncludesFolderFromNamespaces = (input, namespaces) => {
  return Object.keys(namespaces).reduce((acc, curr, index, arr) => {
    acc += path.relative(
      path.join(process.cwd(), input),
      path.join(__dirname, namespaces[curr])
    );
    if (index + 1 === arr.length) {
      acc += "}";
    } else {
      acc += ", ";
    }
    return acc;
  }, "{");
};

As mentioned in the eleventyConfig.addPlugin(fstack, USER_OPTIONS) you have to define some directories. Currently @factorial/eleventy-plugin-fstack provides the following configuration object:

/**
 * @typedef {object} ELEVENTY_DIRECTORIES
 * @property {string} input
 * @property {string} output
 * @property {string} [includes]
 * @property {string} [layouts]
 * @property {string} [watch]
 */

/**
 * @typedef {object} ASSETS
 * @property {string} base
 * @property {string} css
 * @property {string} js
 */

/**
 * @typedef {object} USER_OPTIONS
 * @property {string} mixManifest,
 * @property {ASSETS} [assets]
 * @property {ELEVENTY_DIRECTORIES} dir
 * @property {import("@factorial/eleventy-plugin-twig").TWIG_OPTIONS} [twig] // just if u use @factorial/eleventy-plugin/twig
 */

You could use this as a starting point and customize to your individual needs:

/**
 * Default userOptions for eleventy
 *
 * @type {USER_OPTIONS} USER_OPTIONS
 */
const USER_OPTIONS = {
  twig: {
    shortcodes: [],
    namespaces: {
      elements: "src/include/elements",
      patterns: "src/include/patterns",
      "template-components": "src/include/template-components",
      templates: "src/include/templates",
    },
  },
  mixManifest: "mix-manifest.json",
  assets: {
    base: "assets",
    css: "css",
    js: "js",
  },
  dir: {
    input: "src/include/templates",
    output: "build",
    layouts: "src/layouts",
    watch: "src/**/*.{css,js,twig}",
  },
};

Acknowledgements

This Eleventy + Factorial Stack plugin uses open source software and would not have been possible without the excellent work of the Eslint, Eleventy, Prettier, debug and @factorial/fstack teams! Thanks a lot!

Sponsored by

eleventy-plugin-fstack's Issues

Configurable package manager

At the moment, Yarn is hard-coded as the package manager in the child process. It would be nice if one could specify which package manager is used in the plugin configuration.

Or maybe auto-detect based on the presence of a specific lock-file? 🤔

eleventy-plugin-fstack/lib/plugin.js

Line 60 in 6d3304a

spawnSync("yarn", ["factorial", "build"], { stdio: "inherit" });

Incompatible with incremental build

Eleventy provides the --incremental flag for builds. This is handy in serve mode for local development, because it skips unchanged files.

This plugin clears the whole build folder, not only the assets folder:

eleventy-plugin-fstack/lib/plugin.js

Lines 39 to 42 in 3838872

	fs.rmSync(path.join(process.cwd(), buildFolder), {
	recursive: true,
	force: true,
	});

Since Eleventy “thinks” all generated HTML files are still there, it only generates the currently changed one. All others are removed by the rm mentioned above.

Documentation for incremental mode in the Eleventy docs.