Staticz

Ruby tool allowing you to write a small website project in haml, sass, scss and js, and compile everything into static files before uploading them to a static server. This project takes a lot of inspiration from Ruby on Rails.

Ruby 3.1.0 or newer (not tested on older versions)

gem install staticz

Create a new project by running

staticz new [name]

To make development as easy as possible, you can run a dev server with

staticz server

Whenever a file is saved, it will rebuild the files, so with a reload on the page you can immediately see what your changes did.

To print out the manifest, run staticz manifest. It will also tell you the resource paths, more about that in resource paths

• haml compiles to html
• sass compiles to css
• scss compiles to css
• js doesn't compile, just copies 1:1
• coffee compiles to js

The manifest defines files that need to be built in order for the website to work. This does not include parts.

For example

Staticz::Manifest.define do
  haml :index

  sub :css do
    sass :main
  end

  sub :scripts do
    js :toggle_nav

    coffee :toggle_nav_but_coffee
  end
end

will build src/index.haml, src/css/main.sass, src/scripts/toggle_nav.js and src/scripts/toggle_nav_but_coffee.coffee. You can nest as many subdirectories as you want.

There are multiple helper methods to simplify your work.

Much like rails, every resource generates a path for you to use. For example src/styles/main.sass translates to styles_main_path.

If you want to include the partial src/nav.haml in your index.haml, you can just use = render "nav". You can also instead use a symbol. You can also pass locals, like = render "nav", locals: {foo: "bar"}.

Note: you don't have to parts that you render in the manifest to avoid creating seperate html files for them. Parts will just be rendered into the view they are called from.

If you wanna include the stylesheet src/styles/main.sass, you can use = stylesheet styles_main_path to link it.

Like with stylesheets, you can use generated routes to link to a resource. = link index_path will translate to src/index.haml. If you want to have text on the link, use = link index_path, text: "foo". You can also nest other haml into like:

= link index_path do
  .bar

Javascript files work the same way. The helper = javascript scripts_toggle_path helps you to link files the same way as links and stylesheets.

If you wanna print an inline svg, just use = inline_svg("full_path"). Full path is for example img/test.svg.

Include = reload_js in the haml's head to enable automatic page reload on rebuild. This will be automatically excluded when using staticz build.

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"

If you want to include a raw file in your build, add file "path/to/file" to your manifest. Example:

Staticz::Manifest.define do
  sub :img do
    file "logo.png"
  end
end

Note: This will not create a path for now

Bundles allow you to combine multiple files into one so you don't have to request n different js/css files in your head.

Both bundle types work as following.

Example folder structure:

index.html

css/
  navigation.scss
  footer.sass

  site_specific/
    index.sass

Now to combine all these into one file, your manifest looks like:

Staticz::Manifest.define do
  haml :index

  sub :css do
    css_bundle :index do
      scss :navigation
      sass :footer

      sub :site_specific do
        sass :index
      end
    end
  end
end

This will create the css bundle css/index_bundle.css. The bundle will be positioned in the folder where the bundle is "opened". Of course this creates a path helper as well.

In a css_bundle, you can use sass and scss. In a js_bundle, you can use js, coffee and react.

You can build the project with staticz build. All files included in the manifest will be built and put into the build folder. In a CI workflow, you can then take the build files and push them to a static website server.