Setup

Requirements

Ruby 3.1.0 or newer (not tested on older versions)

Installation

gem install staticz

Quick Start

To get a simple project up and running, run staticz new [name] --template simple. This will set up a small project for you where you can start off of.

It will create an index.haml and a css/main.sass file for you.

This will be enough to create a simple one pager.

To start the development server, run staticz server. This will spin up a web server at port 3000. Running staticz build will generate the production ready files in the build/ folder. These files can then be uploaded to your static webserver.

It is recommended to read through the manifest page. It will give you insights on what this tool can do.

Manifest

The manifest defines how your project is gonna be built. Here is an example of how it could look like:

Staticz::Manifest.define do
  haml :index

  sub :css do
    sass :main
    scss :main_but_scss
  end

  sub :scripts do
    js :toggle_nav

    coffee :toggle_nav_but_coffee
  end
end

Let's break this manifest down. The first statement, haml :index, means it expects a file called index.haml to be at the root of the src folder. Haml is always compiled into .html, so it will result in index.html.

sub means you are now changing directories to a sub folder. Inside, you see sass :main. This means it expects a file css/main.sass. Since sass is compiled into css, it will generate the file css/main.css.

Similarly, you now tell the manifest that there is a folder called scripts at the manifest root, so src/scripts. In there, it expects to find a toggle_nav.js, and a toggle_nav_but_coffee.coffee. js files are just copied as there is no compiling involved, coffee on the other hand will be compiled into .js files.

Note: all files are expected to be in the src folder.

The idea is that the folder structure doesn't change between development and production.

Supported types

sub defines a sub directory. You can nest any type in it.

haml expects a .haml file and outputs .html.

sass or scss expect a .sass or .scss respectively and output a .css file.

js expects a .js file and outputs .js.

coffee looks for a .coffee file and compiles into .js.

react looks for a .js file and outputs as .js.

file works a bit different. It expects a string as an argument, like "logo.png". This file is then copied over on build.

Printout

When running the development server, you will frequently see something similar to the following printed in the console:

Manifest:
└─ Haml: index ✔ -> index_path
└─ Sub: css
   └─ Sass: css/main ✔ -> css_main_path

This is a representation of the manifest. Let's break each line down:

└─ Haml: index ✔ -> index_path Haml means that this manifest entry is of type haml. index is the name. ✔ means there are no build errors. index_path is the path variable generated for it. It will link to the compiled resource's path.

└─ Sub: css Sub means it's a sub directory entry, in this case css/

└─ Sass: css/main ✔ -> css_main_path This entry is indented, meaning it's inside the Sub above it. css/main where the file is expected. The rest is like the Haml entry.

Bundles

Bundles are special in that they work similarly to sub, but restrict the types that are supported inside them. Bundles are best explained by example.

CSS Bundle

Let's take this manifest as an example:

Staticz::Manifest.define do
  sub :css do
    css_bundle :index do
      sass :main

      sub :index do
        scss :header
        sass :nav
      end
    end
  end
end

First, it expects a css folder in the src directory. Then, it is instructed to start a css bundle. css_bundle :index means it will create an index.css at this location, in this case css/index.css in the build folder. It will then take the main.sass folder in the css folder, and compile it. Then, it will switch to the index folder inside css/. In there, it expects a header.scss and a nav.sass. They will both be compiled. Once everything is compiled, they are put into one singular file.

JS Bundle

Similar to css bundles, javascript bundles allow you to combine js, coffee and react into one file.

Paths

Similar to Rails, staticz generates path names for each resource in the manifest. When running the development server, on each file change you will see something like this:

Manifest:
└─ Haml: index ✔ -> index_path
└─ Sub: css
   └─ Sass: css/main ✔ -> css_main_path

The last part of each manifest entry is a path variable, accessible anywhere in the application. It is useful for links between pages, for setting the src tag of an image etc.

For haml, you can use index_path(shorten: true) to remove the .html at the end.

Templates

When starting a new project, there are multiple templates you can use.

Clean

To create a completely clean project, run staticz new [name] --template clean. This will just create the manifest.rb file, with an empty manifest, plus an empty src folder.

Simple

The simple template will create an index.haml and a css/main.sass. It allows you to get quickly started with a page.

Layout

This template is perfect for a multi page site where only the content changes. It will create a template.haml file, where you can change the part that's the same for each page.

It also generates a nav.haml and footer.haml file for convenience.

Lastly, a index.haml is created. In there, the layout is rendered via = render :template do. Everything in the block is then rendered into the layout.

Helpers

Render

If you want to include the partial partials/nav.haml in your index.haml, you can use = render "partials/nav". Additionally, you can also pass locals, like = render "partials/nav", locals: {foo: "bar"}.

Partials rendered like this don't have to be added to the manifest.

Stylesheets

Including a stylesheet in a .haml file is as easy as adding = stylesheet css_main_path (replace css_main_path with the path variable) in the head tag.

Javascripts

Similar to the stylesheets, you can use = javascript scripts_toggle_path to easily add a javascript file.

Links

To add simple links, you can use = link index_path, replacing index_path with the link you want. You can also pass a text parameter to add text to the link, like = link index_path, text: "foo". Pass a block to add custom content like

= link index_path do
  .bar

Inline SVG

If you wanna print an inline svg, just use = inline_svg("full_path"). Full path is for example img/test.svg. Resources like this don't have to be added to the manifest.

Automatic Page Reload

Staticz has a built in way to reload your page if there were any changes to the source files or manifest. To enable this, add = reload_js into the head of the page. This will be ignored with staticz build.

React

A new experimental feature is React. It is a very basic implementation that does only support very basic components. The current restrictions are: 1. Only function components are supported 2. Behaviors like useState need to be prefixed with React., for example React.useState(). 3. import statements are not supported. If you wanna use special libraries like axios for web requests, it will be more complicated. 4. Two statements are needed in your html file to make a component work. Helpers exist for this

Example: manifest.rb

Staticz::Manifest.define do
  haml :index

  sub :components do
    react :search
  end
end

src/components/like_button.js

function LikeButton(props) {
  const [liked, setLiked] = React.useState(false);

  return (
    <React.Fragment>
      {liked ? (
        <div>You liked</div>
      ) : (
        <button
          onClick={() => setLiked(true)}
        >Likey no</button>
      )}
    </React.Fragment>
  );
}

src/index.haml

%html
  %head
    -# Include rails js files and generate script src tags for your components (you can pass multiple paths)
    = react search_path

  %body
    -# Generate tag into which the component is mounted, first is the js name, second is the css class (optional)
    = react_component "LikeButton", "like-button"

    -# Mount components (you can pass multiple component names)
    = react_mount "LikeButton"

Ruby Code

If you want to have some more complex ruby code supporting your page, staticz has you covered. You can create a lib folder in the root of the project. Every .rb file in there is loaded and reloaded when changed.

Production

In a CI/CD environment, you can run staticz build, which will build your full manifest and output the site to the build/ folder. This folder can then be copied to your webserver.