CLI Usage

Have you installed jamrock already?

Jamrock will install itself at your $HOME/.local/bin path, ensure that destination is within you $PATH to enable the binary.

Installation

curl -L get.jamrock.dev | bash
...
jamrock --version
■ Jamrock v0.0.0 (node v23.6.0, HEAD)

Parameters

Additional arguments like FOO=bar will expand the process.env object, e.g. jamrock build NODE_ENV=production PORT=80

You can also use ./bin/{node,deno,bun} if you have the required runtime installed.

Tasks

Run jamrock --help for a quick glance:

■ Jamrock v0.0.0 (node v22.4.0, HEAD)

Usage: ./bin/{node,deno,bun} <COMMAND> [OPTIONS]

  init   Generates a new application into the given directory
  serve  Starts the web-server on the given --port and --host
  build  Compiles *.{md,html} sources into server-components
  route  Prints the available routes found

Options:

  --src      Directory of *.{md,html} files to compile (default is ./pages)
  --dest     Destination for compiled files (default is ./build)
  --watch    Enable file-watching on the web-server
  --write    SSG from compiled sources into destination
  --prefix   Prefix for bundled resources
  --target   Value for <base href="..." /> (default is /)

  --port     The port number to bind the web-server
  --host     The host address to bind the web-server

  --uws      Use uWebSockets.js instead of native HTTP (node)
  --https    Enable HTTPS (requires SSL_KEY_FILE and SSL_KEY_FILE)

  --dts      Produce the .d.ts definitions from web-server routes
  --name     Filter routes by name (contains)
  --path     Filter routes by path (contains)
  --method   Filter routes by method (exact match)

init

This action create a new project into the target directory, e.g.

jamrock init my-app

If the directory already exists you'll be warned, but you can --force to overwrite everything in the target directory.

serve

Spins up a web-server with optional live-reload support, intended for production and development.

Use --watch to enable the development mode, --src and --dest to configure the source and destination folders respectively.

build

Compiles everything down as modules, intended for production.

Use the --prefix to setup a different path for loading ESM from sources, e.g. /@/path/to/component.html (the default is @)

write

Execute all compiled sources to produce static pages, it will derive its configuration from <DEST_DIR>/index.json.

This removes dynamic server-side JavaScript usage, only compiled components that can be downloaded without server dependencies will work.

route

This action will show the declared routes from pages and middleware found in the sources.

You can filter out the matching routes with the --name, --path and --method flags respectively.

By using the --dts flag, this action will write a routes.d.ts file.

We don't support TypeScript yet, but you should be able to write your own .ts modules and consume the generated modules from your code on a separate process.

As long as you compile your .ts modules and they become reachable by import calls on runtime, the framework would work fine.

Being said, you may find a proof of concept of this is on the ./scripts/check.ts file on this repository.

---

dev.config.mjs

Some options can be configured through a module file, this is because they would need you to load additional modules.

redis

Redis is encouraged for production, since the sessions and pub/sub support is stored in memory by default, which is intended for development only.

// enables the built-in support for Redis
export default {
  redis: true,
};

// enables and configure the Redis connection
export default {
  redis: {
    url: '...',
  },
};

unocss

If you want to use UnoCSS make sure you have the appropriate unocss.config.mjs module on the ./pages directory, stylesheets will be calculated from the used classes by rendered components on every request.

// enables the built-in support for UnoCSS
export default {
  unocss: true,
};

markdown

Specific options for markdown are set here, for now you can enable emojify and twemoji only.

// enable emoji shortcuts and inlining as images
export default {
  markdown: {
    emojify: true,
    twemoji: true,
  },
};

generators

// configure support for preprocessors
export default {
  less: await import(typeof Deno !== 'undefined'
    ? 'npm:less'
    : 'less'),
};

The typeof Deno is a dirty-check for making the configuration cross-runtime, otherwise it may not work as expected. Bun and NodeJS are pretty OK without the npm: prefix.

---

Development

Run jamrock server --watch to start watching from the ./pages directory.

You can have other stuff on this folder but it will be ignored, only .md and .html files and their dependencies are watched.

The command above will not fail even if the directory does not exists, the watcher will work as you start adding files.

Use jamrock dev as shortcut for this task.

---

Production

Run jamrock serve and that's it!

Just make sure you have built your pages first.