Build and Vite integration

@netscript/fresh ships a Vite plugin that wires a Fresh workspace into the build: it resolves NetScript app aliases, maps environment variables into import.meta.env, and generates route manifests at build and dev time. Reach for it when you set up the Vite config for a NetScript Fresh app and want aliases, env exposure, and route manifest generation handled in one place.

The plugin factory

createNetScriptVitePlugin(options) is the single entry point. It accepts a NetScriptVitePluginOptions object and returns a NetScriptVitePlugin — the package-owned view of the Vite plugin hooks NetScript Fresh relies on. Add the returned plugin to the plugins array of your Vite config.

The returned plugin runs with enforce: "pre", so its hooks order ahead of most other plugins. It contributes four things:

• Config defaults through the config hook, which returns Vite config defaults for NetScript Fresh workspaces.
• Alias resolution through the resolveId hook, which resolves NetScript app aliases to absolute file paths.
• Route manifests through the buildStart hook, which generates route manifests when the Vite build starts.
• Dev-server watchers through the configureServer hook, which registers development-server watchers for route manifests.

Basic setup

A minimal integration points the plugin at the Fresh app root. With no alias entries supplied, the plugin generates aliases from the app root.

import { createNetScriptVitePlugin } from "@netscript/fresh";

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  workspaceRoot: ".",
});

export default {
  plugins: [netscript],
};

Aliases

Aliases are resolved through resolveId. There are two ways to control them.

Supply explicit aliasEntries to use a fixed set of aliases instead of generated ones. Each NetScriptViteAlias has a find (the import specifier prefix or exact specifier to match) and a replacement (the filesystem path that replaces the matched specifier).

import {
  createNetScriptVitePlugin,
  type NetScriptViteAlias,
} from "@netscript/fresh";

const aliasEntries: NetScriptViteAlias[] = [
  { find: "@app/", replacement: "./app/" },
];

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  aliasEntries,
});

Alternatively, let the plugin generate aliases by listing app-root-relative aliasDirectories and an aliasPrefix:

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  aliasPrefix: "@app/",
  aliasDirectories: ["islands", "components"],
});

Environment variables

Use envMappings to expose environment values through import.meta.env. Each NetScriptViteEnvMapping reads a source key from the provided environment map, defines a target key on import.meta.env, and may supply a fallback value used when the source key is absent. Provide the source values through env.

import {
  createNetScriptVitePlugin,
  type NetScriptViteEnvMapping,
} from "@netscript/fresh";

const envMappings: NetScriptViteEnvMapping[] = [
  {
    source: "PUBLIC_API_URL",
    target: "VITE_API_URL",
    fallback: "http://localhost:3000",
  },
];

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  envMappings,
  env: Deno.env.toObject(),
});

Route manifests

Route manifest generation runs in the buildStart hook for builds and through configureServer watchers during development. Configure it with routeManifest, a NetScriptRouteManifestOptions object.

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  routeManifest: {
    enabled: true,
    routesDir: "./app/routes",
    outputPath: "./app/_routes.gen.ts",
    logLevel: "changes",
  },
});

logLevel accepts "silent", "changes", or "verbose".

Dev-server filesystem access

The plugin sets up the Vite dev server's filesystem allow-list. watchPaths adds paths watched by the dev server, allowFsPaths adds filesystem paths the dev server is allowed to serve, and includeWorkspaceRootInFsAllow controls whether workspaceRoot is included in the filesystem allow-list.

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  workspaceRoot: ".",
  watchPaths: ["./app/routes"],
  allowFsPaths: ["./packages"],
  includeWorkspaceRootInFsAllow: true,
});

API summary

NetScriptVitePluginOptions fields

NetScriptVitePlugin hooks

Related

• The Fresh page model
• Pages and the define-page builder
• Routing and route contracts
• Data loading and the query cache
• Server-validated forms
• Deferred and streaming UI
• Interactive islands
• Error handling and diagnostics
• Testing Fresh pages
• Examples and sandbox
• Web Layer overview
• Live dashboard tutorial