Getting Started

Installing Kalastatic

Once Kalastatic is published, it is easy to include it into your project as a node module:


npm require kalastatic

However, if you are looking for some demo content to help get you started, you will soon be able to use the npm create command (once we have finished developing it):


npm create kalastatic

When running the create command, you will be prompted with questions about which types of demo content that you'd like to start with, including pages, components, styleguide, and drupal theme integration.

Configuring Kalastatic

Since Kalastatic is a very simple system, its configuration is also very simple. Simply create a kalastatic key in your package.json to store the settings:


"kalastatic": {
}

You can look at the package.json file for this demo site to get an idea of the overall structure.

source and destination

The first two configuration items that you need to set are source and destination. Kalastatic will look in the source directory to find html.twig files to process, compile them into html files, and place them in the destination directory.


"kalastatic": {
  "source": "pages",
  "destination": "build"
  }
}

The destination directory will also be prepended to any destinations for assets, stylesheets, and scripts specified (see below).

namespaces

The second configuration item is the namespaces item, which contains an array of directories that should be used for twig namespaces, with each item mapping a namespace name to a corresponding directory:


"kalastatic": {
  "source": "pages",
  "destination": "build",
  "namespaces": {
    "components": "components",
    "templates": "templates",
    "pages": "pages"
  }
}

Having these namespaces will allow for things like pages extending templates in the @templates/ namespace and embedding components using the @components/ namespace. In addition, Kalastatic will generate a list of files in each namespace, and pass the list to the twig files in a namespaceFiles variable. See the Namespace Files section below for more info.

These namespaces are just common ones that we tend to use, but they can be named and organized in whatever way that makes sense for your project, along with adding additional items. For example, if you are buiding a styleguide, there may also be a @styles/ namespace to contain sample twig files with example code and a @styleguide/ namespace to contain styleguide-specific templates.

assets

If you have files that you would like to deploy without any processing needed to be done, such as image files, you can add a assets configuration item with an array of destination and source directories or individual files, and the files will be simply copied from one to the other during the build process.


"kalastatic": {
  "source": "pages",
  "destination": "build",
  ...
  "assets": {
    "assets": "assets"
  }
}

styles

If you have scss files that need to be processed into css files, you can include a styles array with individual source and destination filenames (wildcard patterns have not actually been tested yet), and Kalatatic will use the node sass library to process those files:


"kalastatic": {
  "source": "pages",
  "destination": "build",
  ...
  "styles": {
    "styles/styles.scss": "styles.css"
  }
}

An array of filenames processed as part of the stylesheet compilation are passed into the twig rendering process in the stylesheets variable, which can be used to automatically add stylesheets to your main html template:

{{ stylesheets }}

Note that beyond the files to compile, there is no configuration available for changing how the scss is processed, so if you have a more complicated compilation process, you can just leave out this configuration item and set up your own process with the compilier and settings of your choice.

scripts

Much like with styles, you can specify a scripts parameter, which copies the script files from the source to the destination specified:


"kalastatic": {
  "source": "pages",
  "destination": "build",
  ...
  "scripts": {
    "js/main.js": "main.js"
  }
}

There is no processing done on the js files, so you could move them using the assets parameter, but the files specified by the scripts parameter are also passed into the twig file in a variable called scripts that can be used to automatically populate the script tags in your html template:

{{ scripts }}

libraries

Similar to the libraries.yml files that are provided by Drupal modules and themes, you can define a library for Kalastatic in the package.json configuration array:

"kalastatic": {
  "source": "pages",
  "destination": "build",
  ...
  "libraries": {
    "details-tabs" : {
      "stylesheets": {
        "libraries/details-tabs.scss": "libraries/details-tabs.css"
      },
      "scripts": {
        "libraries/details-tabs.js": "libraries/details-tabs.js"
      }
    }
  }
}

An example library configuration in the package.json file showing how you define the stylesheets and scripts for a library.

Note that unlike Drupal, each item requires source and destination for the file, just like the stylesheets and scripts parameters for the main Kalastatic configuration.

If you provide a scss file for the stylesheets instead of a css file, it will be compiled when processed (which is why these definitions eschew the innacurate js and css keys that Drupal uses for its library definitions).

After you define the library, you can call the attach_library function in a Twig template, and only at that point will the specified files be added to the scripts and stylesheets variables that are passed into the Twig templages by Kalastatic upon processing.

Github Pages and base_url

Kalastatic can be easily deployed to Github pages for hosting the compiled static files. Here is the workflow that this site uses:


name: Build and Deploy a Branch to GH Pages
on:
  push:
    branches:
      - main
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v3
      - name: npm Install
        env:
          base_url: '/kstat_test'
        run: |
          npm install
          npm run build
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: build
          # Remove previous build files
          clean: true

The contents of our gh-pages.yml file that deployes that compiles the pages for this site and deploys them to Github Pages.

When hosting your site in an environment like Github Page, the site root may have a base path in front of it, so Kalastatic looks for a base_url environment variable, which you can then prepend to any links, image sources, or styleguide and script includes.