zamaneh-builds v1.0.0

Zamaneh Builds

Zamaneh builds static websites with large content archives. For this we need a performant, memory-efficient static site generator (SSG) that gives full flexibility to shape API requests, traffic to and from the CMS, and build-time data transformation. With these requirements in mind, Zamaneh Builds was born.

Vision

To the best of our knowlegde, no other SSG on the market supports the generator pattern to enumerate paths or objects in any domain. But the generator pattern is a good idea for certain use cases.

The vision for Zamaneh Builds is to provide a canonical example of why generators are a good idea in certain use cases, so that other SSGs are encouraged to support the generator pattern for enumerating paths (or objects).

Static Site Generator

Zamaneh Builds is a static site generator that supports large (100,000+) article archives. Zamaneh Builds is fast and memory efficient, and allows for flexible content fetch strategies. Zamaneh Builds additionally provides a nice, easy-to-use development and (editorial) preview environment.

• Fast and memory efficient builds.
• Support for huge content archives (100,000+ articles).
• Out-of-the-box support for (editorial) previews.
• Convenient, fast and easy-to-use development environment.
• Uses Nunjucks as a complete and extensible templating language.

Zamaneh Builds is developed with the needs of a publisher, juggling several content-heavy websites and archives that run into the tens to hundreds of thousands of articles, in mind.

Getting started

Create a project

Create a directory for your project using the mkdir command and move into that directory:

mkdir my-project && cd my-project

Installation

Installing Zamaneh Builds into a project requires a package.json file. With the npm command(provided by Node.js) you can create one by running npm init.

Now you can install zaamneh-builds:

npm install zamaneh-builds`

CLI

Run zamaneh-builds dev server

Now you'll be able to start a dev server.

zamaneh-builds dev as an entry in npm scripts or straight npx zamaneh-builds dev from your terminal in your project root.

Run zamaneh-builds production build

And you can run a production build.

zamaneh-builds build as an entry in npm scripts or straight npx zamaneh-builds build from your terminal in your project root.

Configuration

Example

zamaneh-builds dev --port 3000 --nunjucksConfig lib/nunjucks-config.js

Javascript API

If you don't want to use the CLI you can also create Javascript files from where you can start a dev server and/or run a production build.

Run zamaneh-builds dev server

const { dev } = require('zamaneh-builds');
dev();

Run zamaneh-builds production build

const { buildHtml } = require('zamaneh-builds');
buildHtml();

Configuration

The configuration options are the same. Zamaneh builds exports a defineConfig function that you can use to create you configuration. This makes sure all default are being set and filepaths are correctly setup for internal usage.

Here is an example on how you would configure zamaneh-builds when using the Javascript API:

const { buildHtml, defineConfig } = require('zamaneh-builds');
const config = defineConfig({
  srcDir: 'src',
  outDir: 'dist',
  port: 3000,
  nunjucksConfig: 'lib/nunjucks-config.js'
});

buildHtml({ config });

Project structure

Zamaneh Builds leverages an opinionated folder structure for your project in order to work. Your project should include the following directories:

• data/*
• pages/*

With the default configuration you can create these directories inside a src folder or you can configure your own input directory.

Defining static routes and getting data

Inside the pages folder, create a subfolder with the name of the page that you'd like to define. In this folder you, create an index.njk file that is used as the page template.

In the same folder, you can add an index.data.js file that exports a function, which returns the data for the page. If you return an array of objects, a separate page will be generated for each object in the array, meaning you need to generate a page with dynamic path parameters. Let's explain how this works.

Dynamic routes

A page file can specify dynamic route parameters in its filename to generate multiple pages based on the same template. For example, pages/blog/:id/index.njk will generate a blog post for every item in the array that is returned from pages/blog/:id/index.data.js. Note that every item in the array returned from the data file needs to have a property id.

You are free to us multiple dynamic route parameters as long as every item in the array returned from the corresponding data file has properties resembling the route parameter.

Global data

In the data folder you can add a JavaScript file that exports a function. Zamaneh Builds makes the return value of that function available in templates in the global variable. This global variable is an object with camel-cased attributes, one for each file in the data folder. For example, the data returned by the default export of data/app-navigation-items.js will be available as global.appNavigationItems.

Templates

Nunjucks is used as a template language.

In all templates you can use the following variables:

• global: The global data containing all slugified data filenames coming from the data folder.
• page: The data for the current page returned by the index.data.js file.
• params: The dynamic route params as an object.
• url: The url of the current page.

Nunjucks configuration

It makes sense that at some point you want to extend Nunjucks and use custom template tags, filters and/or globals. You can do this by using the eleventyConfig configuration option. It accepts the path to a configuration file. The configuration file should export a default function where the the nunjucksEnvironment is passed to as an argument. You can extend the enviroment from there, for more info see the Nunjucks environment documentation.

See below an example where we add a custom filter:

Dev command:

npx zamaneh-builds --nunjucksConfig=lib/nunjucks-config.js

// lib/nunjucks-config.js
module.exports = function (nunjucksEnvironment) {
  nunjucksEnvironment.addFilter('slugify', slugify);
};

function slugify(string) {
  return string
    .toLowerCase()
    .replace(/[^\w ]+/g, '')
    .replace(/ +/g, '-');
}

From now on you can use the slugify filter inside your templates:

<h1>{{ 'slugify this heading' | slugify }}</h1>

Will output:

<h1>slugify-this-heading</h1>

Library development

If you want to work on the library, great!

Get started by cloning Zamaneh Builds repository:

git clone git@github.com:ZamanehMedia/zamaneh-builds.git

Run npm install to install all dependencies:

npm install

Npm link the project locally by running npm link in the root and npm link zamaneh-builds in the example folder.

See the npm scripts available in the package.json inside the example folder in order to see different builds.