or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-function.mdbuild-output.mdcache-management.mdframework-integration.mdindex.md
tile.json

tessl/npm-vercel--static-build

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vercel/static-build@1.0.x

To install, run

npx @tessl/cli install tessl/npm-vercel--static-build@1.0.0

index.mddocs/

Vercel Static Build

Vercel Static Build is a comprehensive build runtime for Vercel that automatically detects frontend frameworks and builds static websites and single-page applications with zero configuration. It supports automatic framework detection for popular tools like Next.js, React, Vue, Angular, and static site generators, handles dependency installation across multiple package managers, executes build commands with proper environment setup, and optimizes output for production deployment.

Package Information

  • Package Name: @vercel/static-build
  • Package Type: npm
  • Language: TypeScript
  • Installation: This package is typically used as a Vercel build runtime, not directly installed in user projects

Core Imports

import { build, prepareCache, version } from "@vercel/static-build";

For CommonJS:

const { build, prepareCache, version } = require("@vercel/static-build");

Basic Usage

import { build, prepareCache, version } from "@vercel/static-build";
import type { Files, Config, Meta, BuildV2, PrepareCache } from "@vercel/build-utils";

// Primary build function for static sites and SPAs
const buildResult = await build({
  files: downloadedFiles,        // Files from deployment
  entrypoint: "package.json",    // Entry point file
  workPath: "/build/workspace",  // Working directory
  repoRootPath: "/build/repo",   // Repository root path
  config: {                      // Build configuration
    zeroConfig: true,
    outputDirectory: "dist"
  },
  meta: {                        // Build metadata
    isDev: false,
    skipDownload: false,
    cliVersion: "34.2.0"
  }
});

// Result contains optimized files, routes, and images
console.log(buildResult.output);  // Static files and serverless functions
console.log(buildResult.routes);  // Route configuration
console.log(buildResult.images);  // Image optimization config

Architecture

Vercel Static Build is designed around several key components:

  • Framework Detection: Automatic detection of 50+ frontend frameworks using package.json dependencies
  • Zero Configuration: Intelligent defaults for build commands, output directories, and deployment optimization
  • Multi-Language Support: Handles JavaScript/TypeScript, Python, Ruby, and Go-based static site generators
  • Build Output APIs: Supports v1, v2, and v3 Build Output APIs for different deployment targets
  • Development Mode: Integrated dev server support with hot reloading and port management
  • Caching Strategy: Intelligent caching for dependencies, build artifacts, and framework-specific assets

Capabilities

Primary Build Function

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

const build: BuildV2 = async ({
  files,
  entrypoint,
  workPath,
  repoRootPath,
  config,
  meta = {},
}: BuildOptions): Promise<BuildResultV2>;

interface BuildOptions {
  files: Files;
  entrypoint: string;
  workPath: string;
  repoRootPath: string;
  config: Config;
  meta?: Meta;
}

type BuildResultV2 = BuildResultV2Typical | BuildResultBuildOutput;

interface BuildResultV2Typical {
  output: Files;
  routes?: Route[];
  images?: Images;
  wildcard?: Array<{ domain: string; value: string; }>;
}

interface BuildResultBuildOutput {
  buildOutputVersion: 3;
  buildOutputPath: string;
}

Build Function

Cache Management

Cache preparation functionality for optimizing build performance across deployments with framework-specific caching strategies.

function prepareCache(options: PrepareCacheOptions): Promise<Files>;

interface PrepareCacheOptions {
  files: Files;
  entrypoint: string;
  repoRootPath: string;
  workPath: string;
  config: Config;
}

Cache Management

Build Output Processing

Support for different Build Output API versions (v1, v2, v3) with automatic detection and processing of static files, serverless functions, and middleware.

// Build Output V1
function readBuildOutputDirectory(options: {
  workPath: string;
  nodeVersion: NodeVersion;
}): Promise<BuildOutputV1Result>;

// Build Output V2
function getBuildOutputDirectory(workingDir: string): Promise<string | undefined>;
function createBuildOutput(workPath: string): Promise<BuildResultV2>;

// Build Output V3
function getBuildOutputDirectory(path: string): Promise<string | undefined>;
function readConfig(path: string): Promise<{ cache?: string[] } | undefined>;

Build Output Processing

Framework Integration

Specialized utilities for framework-specific optimizations including analytics plugin injection for Gatsby and Nuxt.js applications.

// Gatsby utilities
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;

// Nuxt utilities  
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;

Framework Integration

Core Types

interface Config {
  zeroConfig?: boolean;
  distDir?: string;
  outputDirectory?: string;
  buildCommand?: string;
  devCommand?: string;
  installCommand?: string;
  framework?: string;
}

interface Meta {
  isDev?: boolean;
  skipDownload?: boolean;
  cliVersion?: string;
  buildId?: string;
}

interface Files {
  [filePath: string]: FileFsRef | FileBlob | Lambda | EdgeFunction;
}

// File system reference for static files
interface FileFsRef {
  fsPath: string;
  contentType?: string;
}

// Binary file blob for in-memory files  
interface FileBlob {
  data: Buffer;
  contentType?: string;
}

// Serverless function configuration
interface Lambda {
  files: Files;
  handler: string;
  runtime: string;
  memory?: number;
  maxDuration?: number;
  regions?: string[];
}

// Edge function configuration
interface EdgeFunction {
  deploymentTarget: 'v8-worker';
  entrypoint: string;
  files: Files;
  name: string;
}

interface Route {
  src: string;
  dest?: string;
  headers?: { [key: string]: string };
  methods?: string[];
  status?: number;
  continue?: boolean;
  middlewarePath?: string;
}

interface ImagesConfig {
  domains: string[];
  sizes: number[];
}

interface NodeVersion {
  major: number;
  range: string;
  runtime: string;
}

interface BuildOutputV1Result {
  staticFiles: Files | null;
  functions: Record<string, Lambda> | null;
  routes: Route[] | null;
  images: ImagesConfig | null;
  build: BuildConfig | null;
}

interface BuildResultV2 {
  output: Files;
  routes?: Route[];
  images?: ImagesConfig;
  buildOutputVersion?: number;
  buildOutputPath?: string;
}

interface BuildConfig {
  cache: string[];
}

const version: 2;