Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ




    A dependency-light static site generator

    Alchemy is a static site generator for Node.js that's been heavily inspired by tools such as Metalsmith and Jekyll, but to be as dependency-light and efficiency focused as possible.

    Featuring a "transmuter system" and a clean, chainable API, Alchemy allows users to create their own transmuter functions to take an input source and transmute it into something else. This is very useful and flexible when performing operations such as converting markdown to HTML, appending new YAML with an array of certain content, pre-processing Sass to CSS, file templating such as Handlebars, or really any other file manipulation that can be of use.

    Getting Started

    • npm i @alchemy-js/alchemy --save


    Alchemy's chainable API executes sychronously. It's also important to note that the order in which transmute functions are chained can impact the output, depending upon what the expected behavior of each function is. With this in mind, calls to transmute adds the passed in function to a queue. Once the build method is executed, Alchemy executes the contents of each transmute function from the previously created queue, following the FIFO (first in, first out) concept. For example, if a transmuter leverages a templating engine to convert Handlebars content to HTML and another transmuter is expecting the incoming file to already be an HTML document, then these must be in order, from top-down. If they were reversed, the process would fail.

    Public Methods

    • Returns a new instance of Alchemy static site generator
    • Requires an object with values that represent src and dest paths
    • Cleans the destination directory, or creates one if it does not already exist
    • Useful when a file or directory has been removed in between builds
    Alchemy.transmute([function]) (optional)
    • Transmutes file data for site generation
    • Accepts a function that returns a function containing file, and done parameters
      • file is an object containing data related to the file that is currently being processed, specifically:
        • content and data key/values from the gray-matter package
        • Results from path.prase - specifically file dir, name, and ext
        • References to src and dest, the arguments passed to the Alchemy function
      • done is a callback function that must be called once transmutations are completed
        • this accepts an object that can contain whatever data that was transmuted from the file object. This transmuted data is then passed along to the next method in the chain
          • e.g., { content: [string], data: [object], dir: [string], name: [string], ext: [string] }
        • additionally, there is a property that can be passed to ignore a file entirely from generation, having it not appear in the dest directory once the entire chain executes
          • e.g., { ignore: [boolean] }
        • if a file is not transmuted or ignored, call done() with no arguments to continue the process
    • Builds the site in the dest directory
    Alchemy.watch([array]) (optional)
    • Watches an array of directories for changes
    • Results in cleaning and building the project

    Basic Example

    const Alchemy = require('@alchemy-js/alchemy');
    Alchemy({ src: './data', dest: './public' })
      // optional transmute method accepts a closure to operate upon `{ file }` data,
      // followed by calling `done()` to move to the next chained method
        // some config data for the foobar func here

    Transmuter Function Example

    const Alchemy = require('@alchemy-js/alchemy');
    const extUpdater = (options) => {
      const { find, replace } = options;
      return (file, done) => {
        if (file.ext === find) {
          done({ ext: replace })
    Alchemy({ src: './data', dest: './public' })
      // extUpdater now changes each file extension from `.md` to `.html`
        find: '.md',
        replace: '.html',



    npm i @alchemy-js/alchemy

    DownloadsWeekly Downloads






    Unpacked Size

    24.3 kB

    Total Files


    Last publish


    • avatar