Luath

Getting Started

Overview

Luath ( /l̪ˠuə/ - Scottish Gaelic for fast ) is a front-end development and build tool for Deno with:

  1. A development server for serving your application via ESM with hot module replacement and support for a wide range of modern features.
  2. A build command for bundling your application code with deno-rollup.

Running Your First Luath Project

Install the Luath CLI using Deno:

$ deno install -fqA --unstable https://deno.land/x/luath@0.9.1/luath.ts

Then follow any prompts from the Deno command. For example, you may need to add the Deno bin directory to your path:

$ export PATH="$HOME/.deno/bin:$PATH"

You are now set to use Luath. Let's try it out with one of the Luath repo examples:

  1. Clone the Luath repo locally:
    2. $ git clone git://github.com/cmorten/luath.git --depth 1
  2. Navigate to the desired example:
    3. $ cd luath/examples/react
  3. Run the example with the luath serve command:
    4. $ luath serve
  4. Open http://localhost:4505 in a browser.
  5. Start editing some of the example files and keep an eye on the browser!

CLI

To view the available commands and flags for the Luath CLI you can use the luath --help command:

$ luath --help

  Usage:   luath [root:string]
  Version: v0.9.1

  Description:

      CLI for fast front-end development in Deno.

  Options:

      -h, --help                  - Show this help.
      -V, --version               - Show the version number for this program.
      -c, --config    [filename]  - Use this config file (if argument is used but value is unspecified, defaults to luath.config.ts).
      -p, --port      <port>      - Port to run the server on. (Default: 4505)
      -h, --hostname  <hostname>  - Hostname to run the server on.  (Default: "0.0.0.0")

  Commands:

      serve  [root]  - Serve the application with HMR.
      build  [root]  - Build the production assets.
      run    [root]  - Serve the production assets.

For help with subcommands similarly provide the help flag, for example luath serve --help.

Getting Involved

Please refer to the Luath repo's contributing guide.

If you need help or have any queries, reach out to the Deno community on the Deno Discord or GitHub Issues.

Features

Hot Module Replacement

Luath provides Hot Module Replacement ( HMR ) over ESM to allow updates to an application without needing to refresh the page, letting you focus on your code and yeilding faster iteration. Via the plugin system, you easily use the first-party HMR integration for React Fast Refresh or any compatible third-party integration.

The Luath HMR works by setting up a Web Socket ( WS ) connection between the Luath server and the client, and then setting up a file watcher which signals to the client when a file has been modified, created or removed. When the client receives the signal from the WS, it then re-imports the appropriate modules, updating your live application without the need to refresh the page.

JSX And TypeScript

Luath supports the use of .ts, .jsx and .tsx files out of the box.

This support is provided by deno-rollup, initially using the built-in JSX and TypeScript loader which interally invokes the Deno.emit() API before gracefully transitioning to a lazy-loaded esbuild plugin. This allows Luath to transpile your code at a great pace, often with HMR updates live in the browser within 10 - 50ms.

PostCSS And CSS Modules

Luath supports the use of .css files out the box, with automatic <link> and <style> injection and HMR support.

.css files imported into code are automatically treated as CSS Modules, and you can retrieve the processed CSS class names from properties on the default export. The full processed CSS string can also be accessed via the name stylesheet export.

// style.css
        
.darkMode { background: #2d2d2d; }
// mod.ts
        
import styles, { stylesheet } from "./style.css";
        

        
// Access processed CSS as a string
        
console.log(stylesheet);
        

        
// Access processed CSS class names
        
document.body.classList.add(styles.darkMode)

CSS Module support is provided by the deno-rollup postcss plugin.

Luath is also configured to support CSS @import statements, and will inline imported CSS using postcss-import. Updates to imported CSS will result in HMR of the appropriate styles, providing instant feedback as you style your application.

CSS imported into your application by <link> tags in your index.html also benefit from the same PostCSS processing and HMR as direct CSS imports into your code.

JSON

Luath supports the use of .json files out the box, with automatic HMR support.

// Import entire JSON object
        
import json from "./fixture.json";
        

        
// Import a named export from the JSON object
        
import { prop } from "./fixture.json";

JSON support is provided by the deno-rollup json plugin.

Images

Luath supports the use of .jpg, .png, .gif, .svg, and .webp files out the box, with automatic HMR support. These can be imported into your code as base64 encoded images. Note that this means they will be 33% larger than the size on disk, so this feature is best used only for small images.

import icon from "./icon.png";
      
const iconElement = document.createElement("image");
      
iconElement.src = icon;
      
document.body.appendChild(iconElement);

Image support is provided by the deno-rollup image plugin.

Static File Serving

All assets in the root directory of your application will be served by Luath, meaning you can access them on the root path / of the server.

If you have assets that you want to be served by Luath, but without any processing and bundling ( e.g. robots.txt ) then you can place the assets in a ./public directory in the project root. All assets in the ./public directory will be statically served on the root path / of the server as-is.