Migrating from Nuxt

Silgi has the shape of Nuxt: file-based pages, layouts, route middleware, a server/ folder, useFetch, useState, route rules, modules and layers. The names are often the same. Four things are different from the start:

• You pick the UI library. Nuxt is Vue. Silgi runs React, Vue, Preact, Solid, Svelte or plain HTML, so a Nuxt app moves most easily to @silgi/vue. Hooks return the library's own values, such as a Ref in Vue; see Adapters.
• The server is Web standards. There is no h3 or Nitro. A handler gets a SilgiEvent that holds a Web Request, and returns a value or a Response.
• Auto-imports are off. Import from silgi/app, silgi/server and @silgi/<library>, or turn on imports.autoImport.
• Bun builds it. build is Bun.build options, not Vite or webpack. Vite plugins and Nuxt modules do not run.

The tables list a Nuxt name, what to use in Silgi, and where they differ. none means Silgi has no equivalent today. Coming from another framework? See Next, Remix and React Router or SvelteKit.

Folders and files

The path aliases are ~ and @ for app/, and #shared. There is no ~~ or #imports.

A page that reads its data with a handler:

import { useAsyncData, useHead, useRoute } from "@silgi/react";
import type { PageMeta } from "silgi/app";
import { getPost } from "#server";

export const meta = { layout: "blog", middleware: "auth" } satisfies PageMeta;

export default function Post() {
  const { slug } = useRoute().params;
  const { data } = useAsyncData(getPost, () => ({ id: slug as string }));
  useHead({ title: data?.title ?? "Post" });
  return <h1>{data?.title}</h1>;
}

Pages and routing

The file syntax is Nuxt's: [slug], [[slug]], [...slug], (group) folders and parent.vue next to a parent/ folder. Silgi adds [[...path]] for an optional catch-all. See Routing.

Composables and components

A plugin that provides a helper and listens to a hook:

import { definePlugin } from "silgi/app";

export default definePlugin((app) => {
  app.hooks.hook("app:mounted", () => console.log("mounted"));
  return { provide: { hello: (name: string) => `Hello ${name}` } };
});

Forms and mutations

In a Nuxt app a form is usually a @submit.prevent handler that calls $fetch and then refreshes with refreshNuxtData. Silgi has a path with fewer steps: the mutation is a handler, Form action={fn} posts to it with and without JavaScript, and the page's data is read again by itself. A handler with a route keeps working as an API for other clients. See Forms and login and Handlers.

A login that $fetches and then sets the shared state becomes a login handler. The Forms and login guide builds one.

Config keys

import { defineConfig } from "silgi";

export default defineConfig({
  framework: "vue",
  ssr: true,
  app: { baseURL: "/", head: { titleTemplate: "%s · Shop" } },
  runtimeConfig: { apiSecret: "", public: { apiBase: "/api" } },
  routeRules: { "/blog/**": { prerender: true }, "/admin/**": { ssr: false } },
  storage: { cache: { driver: "fs", base: ".data/cache" } },
  preset: "node",
  imports: { autoImport: true },
  components: true,
});

Tasks, database, blob and storage

Nitro's tasks and database and NuxtHub's blob, database and key-value storage have Silgi counterparts. The names are close and the shapes are not, so read each row.

Server utilities

The Nitro and h3 names on the left, with the Silgi name from silgi/server. See Server.

A route that reads the event, as a Nitro handler does:

import { createError, defineHandler, getQuery, getRouterParam, setResponseStatus, useRuntimeConfig } from "silgi/server";

export const getPost = defineHandler({
  route: "/api/posts/:id",
  method: "GET",
  raw: true,
  handler(_, { event }) {
    const { draft } = getQuery(event);
    const id = getRouterParam(event, "id");
    if (!id) throw createError({ status: 400, message: "id is required" });
    setResponseStatus(event, 200);
    return { id, draft: draft === "1", site: useRuntimeConfig(event).public };
  },
});

Modules

defineNuxtModule is defineModule: meta.name, meta.configKey (defaulting to meta.name), defaults (an object or a function of the context), hooks and setup(options, silgi). Options merge as in Nuxt, inline options over the config key over defaults. A module types its options by adding to SilgiModuleOptions with declare module "silgi", so defineConfig checks them. See Modules.

Internationalization

@nuxtjs/i18n is @silgi/i18n, a first-party module with the same route names (about___fr) and a smaller option set. Messages use an ICU MessageFormat subset, not vue-i18n's syntax: rewrite a | b plurals as {count, plural, one {a} other {b}} and linked messages (@:key) as plain text. See Internationalization.

Types and environment

$development applies to silgi dev, $test when NODE_ENV is test, and $production to every other command. $env.<name> applies for --mode <name>, over the block of the kind:

import { defineConfig } from "silgi";

export default defineConfig({
  framework: "react",
  build: { minify: true },
  runtimeConfig: { public: { apiBase: "/api" } },
  $development: { runtimeConfig: { public: { apiBase: "http://localhost:4000/api" } } },
  $test: { storage: { default: { driver: "memory" } } },
  $production: { build: { sourcemap: "linked" } },
  $env: {
    staging: { runtimeConfig: { public: { apiBase: "https://staging.example.com/api" } } },
  },
});

Layers apply their own blocks to their own keys. $env applies by --mode where Nuxt applies it by --envName. A block cannot hold rootDir, extends, dev or another block.

From React Router and Vite

Commands