Rift Logo RiftJS

Rift Documentation

Comprehensive guides and reference for building fast, modern web applications with Rift.

$ npm create rift@latest

Core Concepts & Features

Pages & Routing

Rift uses a file-based routing system. Each file in your src/pages directory becomes a route on your site. You can use .rift, .njk, or .md files for your pages. Dynamic routes and parameters are supported via controller files.

src/pages/post.rift 
---
permalink: /post/:slug
---
<h1></h1>

Controllers

Controllers are TypeScript files that let you fetch data, define params, and control how pages are rendered. Place them in src/controllers and export params() and render() functions. This gives you full control over data and output.

src/controllers/posts.controller.ts 
export async function params() {
  return await getContent('posts/*.md', item => ({
    ...item.metadata,
    content: item.content,
  }));
}

Assets

Static assets (images, icons, etc.) go in src/assets. Rift copies these to your output directory. Reference them in your pages with relative paths.

<img src="/assets/logo.png" alt="Logo" />

Plugins

Rift is fully extensible via plugins. Use official plugins for Markdown, Nunjucks, i18n, RSS, and more—or write your own. Configure plugins in rift.config.ts to customize your build pipeline.

// rift.config.ts
import { defineConfig } from '@riftjs/rift';
import { markdownPlugin, njkPlugin } from '@riftjs/plugins';

export default defineConfig({
  plugins: [markdownPlugin(), njkPlugin()]
});

Frontmatter & Metadata

Define page metadata (permalink, date, tags, etc.) using frontmatter at the top of your files. This metadata is available in your templates and controllers.

--- 
title: My First Post
permalink: /post/my-first-post
date: 2025-05-10
tags: [rift, static site generator]
---

Internationalization (i18n)

Rift supports multiple languages out of the box. Store translations in src/locales and use the i18nPlugin to localize your content.

// src/locales/en.json
{
  "hello": "Hello World"
}

Build Output

All content is compiled to static HTML in your output directory. No client-side JavaScript is included unless you add it yourself. This ensures fast, SEO-friendly sites by default.

Installation

1. Create a Project (Recommended)

The easiest way to get started is with the official starter. This sets up everything for you, including a sample config, pages, and assets.

npm create rift@latest

Follow the prompts to scaffold a new Rift project.

2. Manual Setup (Advanced)

You can also add Rift to an existing project or set up from scratch. Install Rift and create a minimal config file:

npm install @riftjs/rift @riftjs/plugins

Then add a rift.config.js file to your project root:

// rift.config.js
module.exports = {
  plugins: [require('@riftjs/plugins').njkPlugin()]
};

You can now add your pages and assets folders and run Rift CLI commands.

Project Structure

A typical Rift project has the following structure:

src/
  pages/
  controllers/
  assets/
  locales/
rift.config.js

Organize your content, controllers, and assets as shown above for best results.

CLI Commands

npx rift build   # Build your site
npx rift dev     # Start local dev server
npx rift clean   # Remove output directory

Use these commands to build, preview, and clean your Rift project.

Configuration

Configure Rift using rift.config.js or rift.config.ts. Here is a minimal example:

// rift.config.js
module.exports = {
  plugins: [require('@riftjs/plugins').njkPlugin()]
};

See the Plugin Reference for more configuration options.

Pages

Pages are created in the src/pages directory. Each file becomes a route. Use .rift, .njk, or .md files.

src/pages/about.rift 
---
title: About
---
<h1>About Rift</h1>

Templating

Rift supports Nunjucks, Markdown, and custom templates. Use variables and includes for dynamic content.

<h1></h1>


    Rift © 2025 — No magic. No noise.

Assets

Place static files in src/assets. Reference them in your pages with relative paths.

<img src="/assets/logo.png" alt="Logo" />

Plugins

Extend Rift with official and custom plugins. Configure them in your config file.

// rift.config.js
module.exports = {
  plugins: [
    require('@riftjs/plugins').njkPlugin(),
    require('@riftjs/plugins').markdownPlugin()
  ]
};

Plugin API

Write your own plugins to extend Rift. Plugins are functions that receive the Rift context and can modify the build process.

// Example plugin
module.exports = function myPlugin() {
  return {
    name: 'my-plugin',
    onBuild({ config }) {
      // Custom logic here
    }
  };
};