CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-vercel--static-build

A Vercel build runtime for static websites and single-page applications with zero configuration.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

build-function.mddocs/

Build Function

The primary build functionality that handles framework detection, dependency installation, build execution, and output optimization for static sites and single-page applications.

Capabilities

Main Build Function

Executes the complete build process including framework detection, dependency installation, build command execution, and output optimization.

/**
 * Primary build function for static sites and single-page applications
 * @param options - Build configuration and input files
 * @returns Promise resolving to build result with output files, routes, and images
 */
const build: BuildV2 = async ({
  files,
  entrypoint,
  workPath,
  config,
  meta = {},
}: BuildOptions): Promise<BuildResultV2>;

interface BuildOptions {
  /** Downloaded files from the deployment */
  files: Files;
  /** Entry point file (typically package.json or build.sh) */
  entrypoint: string;
  /** Working directory path for the build */
  workPath: string;
  /** The "Root Directory" is assigned to the workPath so the repoRootPath
   * is the Git Repository Root. This is only relevant for Monorepos. */
  repoRootPath: string;
  /** Build configuration options */
  config: Config;
  /** Optional build metadata */
  meta?: Meta;
}

type BuildResultV2 = BuildResultV2Typical | BuildResultBuildOutput;

interface BuildResultV2Typical {
  /** Route configuration for the deployment */
  routes?: Route[];
  /** Image optimization configuration */
  images?: Images;
  /** Static files and serverless functions */
  output: {
    [key: string]: File | Lambda | Prerender | EdgeFunction;
  };
  /** Wildcard configuration */
  wildcard?: Array<{
    domain: string;
    value: string;
  }>;
}

interface BuildResultBuildOutput {
  /** Build Output API version 3 */
  buildOutputVersion: 3;
  /** Build output directory path */
  buildOutputPath: string;
}

Usage Examples:

import { build } from "@vercel/static-build";
import type { Files, Config, FileFsRef, BuildV2 } from "@vercel/build-utils";

// Basic static site build
const result = await build({
  files: {
    "package.json": new FileFsRef({ fsPath: "./package.json" }),
    "src/index.html": new FileFsRef({ fsPath: "./src/index.html" }),
    "src/style.css": new FileFsRef({ fsPath: "./src/style.css" })
  },
  entrypoint: "package.json",
  workPath: "/build/workspace",
  repoRootPath: "/build/repo",
  config: {
    zeroConfig: true,
    outputDirectory: "dist"
  },
  meta: {
    isDev: false,
    cliVersion: "34.2.0"
  }
});

// Development mode with custom configuration
const devResult = await build({
  files: projectFiles,
  entrypoint: "package.json", 
  workPath: "/dev/workspace",
  repoRootPath: "/dev/repo",
  config: {
    zeroConfig: true,
    buildCommand: "npm run build:dev",
    devCommand: "npm run dev",
    framework: "nextjs"
  },
  meta: {
    isDev: true,
    skipDownload: true
  }
});

Framework Detection

The build function automatically detects frameworks based on package.json dependencies and configuration files.

Supported Frameworks:

  • Next.js, Create React App, Gatsby
  • Vue.js, Nuxt.js, Vite
  • Angular, Svelte, SvelteKit
  • Static site generators (Hugo, Jekyll, etc.)
  • And 40+ other frameworks

Detection Process:

  1. Reads package.json dependencies and devDependencies
  2. Matches against known framework dependency patterns
  3. Falls back to manual framework specification in config
  4. Applies framework-specific build optimizations

Build Process Flow

  1. Download and Setup: Downloads deployment files to working directory
  2. Framework Detection: Identifies framework and applies optimizations
  3. Dependency Installation: Installs npm, pip, bundler dependencies as needed
  4. Environment Setup: Configures PATH, environment variables, and build tools
  5. Build Execution: Runs build command (detected or configured)
  6. Output Processing: Processes build output according to Build Output API version
  7. Route Generation: Generates route configuration for framework
  8. Optimization: Applies production optimizations and analytics injection

Development Mode

When meta.isDev is true, the build function starts a development server instead of building static files.

Development Features:

  • Hot reloading with automatic port detection
  • Live proxy to development server
  • Environment variable injection
  • Framework-specific dev command execution
// Development mode configuration
const devBuild = await build({
  files: {},
  entrypoint: "package.json",
  workPath: "./project",
  repoRootPath: "./",
  config: { 
    zeroConfig: true,
    devCommand: "npm run dev"
  },
  meta: { 
    isDev: true 
  }
});

// Returns route configuration proxying to dev server
console.log(devBuild.routes); // [{ src: '/(.*)', dest: 'http://localhost:3000/$1' }]

Error Handling

The build function throws specific errors for common failure scenarios:

  • STATIC_BUILD_NO_OUT_DIR: Output directory missing after build
  • STATIC_BUILD_NOT_A_DIR: Output directory is not a directory
  • STATIC_BUILD_EMPTY_OUT_DIR: Output directory is empty
  • STATIC_BUILD_BINARY_NOT_FOUND: Framework binary version not found

Build Configuration Options

interface Config {
  /** Enable zero-configuration build mode */
  zeroConfig?: boolean;
  /** Legacy output directory path (use outputDirectory instead) */
  distDir?: string;
  /** Output directory (newer alias for distDir) */
  outputDirectory?: string;
  /** Custom build command */
  buildCommand?: string;
  /** Custom development command */
  devCommand?: string;
  /** Custom install command */
  installCommand?: string;
  /** Framework override */
  framework?: string;
}

Meta Options

interface Meta {
  /** Enable development mode */
  isDev?: boolean;
  /** Skip file download (for local development) */
  skipDownload?: boolean;
  /** Vercel CLI version */
  cliVersion?: string;
  /** Unique build identifier */
  buildId?: string;
  /** Avoid top-level npm install in monorepos */
  avoidTopLevelInstall?: boolean;
  /** Development cache directory */
  devCacheDir?: string;
  /** Request path for the build */
  requestPath?: string;
  /** Files that have changed */
  filesChanged?: string[];
  /** Files that have been removed */
  filesRemoved?: string[];
  /** Environment variables */
  env?: Record<string, string>;
  /** Build environment variables */
  buildEnv?: Record<string, string>;
}

Install with Tessl CLI

npx tessl i tessl/npm-vercel--static-build

docs

build-function.md

build-output.md

cache-management.md

framework-integration.md

index.md

tile.json