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

Framework Integration

Name: tessl/npm-vercel--static-build
Author: tessl

Specialized utilities for framework-specific optimizations including analytics plugin injection, environment variable handling, and build command detection for popular frontend frameworks.

Capabilities

Gatsby Integration

Specialized utilities for Gatsby.js applications including Vercel analytics plugin injection and configuration management.

/**
 * Injects gatsby-plugin-vercel into Gatsby configuration for analytics tracking
 * @param dir - Gatsby project directory path
 * @returns Promise that resolves when injection is complete
 */
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;

Usage Examples:

// Note: Import path may vary depending on build setup
// Internal: import * as GatsbyUtils from './utils/gatsby';
// External: import * as GatsbyUtils from '@vercel/static-build/utils/gatsby';
import * as GatsbyUtils from '@vercel/static-build/utils/gatsby';

// Inject Vercel analytics into Gatsby project
await GatsbyUtils.injectVercelAnalyticsPlugin("/project/gatsby-site");

Gatsby Analytics Injection Process:

Environment Variable Setup: Sets GATSBY_VERCEL_ANALYTICS_ID from VERCEL_ANALYTICS_ID
Package.json Update: Adds gatsby-plugin-vercel as dependency if not present
Configuration Injection: Modifies or creates gatsby-config.js with analytics plugin
Backup Creation: Creates backup of existing configuration as .js.__vercel_builder_backup__.js

Generated gatsby-config.js:

const userConfig = require("./gatsby-config.js.__vercel_builder_backup__.js");

// Prefer default export handling
const preferDefault = m => (m && m.default) || m;

const vercelConfig = Object.assign({}, preferDefault(userConfig));
if (!vercelConfig.plugins) {
  vercelConfig.plugins = [];
}

// Add Vercel analytics plugin if not already present
const hasPlugin = vercelConfig.plugins.find(
  (p) => p && (p === "gatsby-plugin-vercel" || p.resolve === "gatsby-plugin-vercel")
);
if (!hasPlugin) {
  vercelConfig.plugins = vercelConfig.plugins.slice();
  vercelConfig.plugins.push({
    resolve: "gatsby-plugin-vercel",
    options: {},
  });
}

module.exports = vercelConfig;

Nuxt.js Integration

Specialized utilities for Nuxt.js applications including web vitals analytics plugin injection.

/**
 * Injects @nuxtjs/web-vitals plugin into Nuxt configuration for analytics tracking
 * @param dir - Nuxt project directory path  
 * @returns Promise that resolves when injection is complete
 */
function injectVercelAnalyticsPlugin(dir: string): Promise<void>;

Usage Examples:

// Note: Import path may vary depending on build setup
// Internal: import * as NuxtUtils from './utils/nuxt';
// External: import * as NuxtUtils from '@vercel/static-build/utils/nuxt';
import * as NuxtUtils from '@vercel/static-build/utils/nuxt';

// Inject Vercel analytics into Nuxt project
await NuxtUtils.injectVercelAnalyticsPlugin("/project/nuxt-app");

Nuxt Analytics Injection Process:

Nuxtrc Configuration: Updates .nuxtrc file with modules[] entry for @nuxtjs/web-vitals
Package.json Update: Adds @nuxtjs/web-vitals as dependency if not present
Module Registration: Uses rc9 library to safely update configuration

Generated .nuxtrc:

modules[]="@nuxtjs/web-vitals"

Framework Detection

Automatic framework detection system that identifies frameworks based on package.json dependencies and applies appropriate optimizations.

/**
 * Detects framework from configuration and package.json dependencies
 * @param config - Build configuration with optional framework override
 * @param pkg - Package.json contents
 * @returns Detected framework object or undefined
 */
function getFramework(
  config: Config | null,
  pkg?: PackageJson | null
): Framework | undefined;

interface Framework {
  name: string;
  slug: string | null;
  logo: string;
  darkModeLogo?: string;
  screenshot?: string;
  demo?: string;
  tagline?: string;
  website?: string;
  description: string;
  dependency?: string;
  sort?: number;
  useRuntime?: object;
  ignoreRuntimes?: string[];
  detectors?: object;
  recommendedIntegrations?: any[];
  defaultVersion?: string;
  settings: {
    buildCommand: SettingValue;
    devCommand: SettingValue;
    installCommand?: SettingValue;
    outputDirectory?: SettingValue;
  };
  defaultRoutes?: Route[] | ((dirPrefix: string) => Promise<Route[]>);
  cachePattern?: string | string[];
  envPrefix?: string;
  getOutputDirName?: (outputDirPrefix: string) => Promise<string>;
}

interface SettingValue {
  value: string | null;
  placeholder?: string;
}

Framework Detection Process:

Manual Override: Check config.framework for explicit framework specification
Dependency Matching: Match package.json dependencies against known framework patterns
Framework Selection: Return first matching framework from frameworks list

Supported Frameworks (examples):

Next.js: dependency: "next"
Create React App: dependency: "react-scripts"
Gatsby: dependency: "gatsby"
Nuxt.js: dependency: "nuxt"
Vue CLI: dependency: "@vue/cli-service"
Angular: dependency: "@angular/cli"
Svelte Kit: dependency: "@sveltejs/kit"

Environment Variable Handling

Framework-specific environment variable injection and prefixing for client-side access.

Create React App Integration:

// Disable CI warnings that fail builds
if (framework?.slug === 'create-react-app') {
  spawnOpts.env.CI = 'false';
}

Framework Prefix Handling:

// Inject VERCEL_ environment variables with framework prefix
if (process.env.VERCEL_URL && framework.envPrefix) {
  Object.keys(process.env)
    .filter(key => key.startsWith('VERCEL_'))
    .forEach(key => {
      const newKey = `${framework.envPrefix}${key}`;
      if (!(newKey in process.env)) {
        process.env[newKey] = process.env[key];
      }
    });
}

Framework Environment Prefixes:

Gatsby: GATSBY_ - Exposes variables to client-side bundles
Next.js: NEXT_PUBLIC_ - Exposes variables to browser
Create React App: REACT_APP_ - Bundled into client code

Build Command Detection

Intelligent build command detection with framework-specific defaults and package.json script fallbacks.

/**
 * Determines appropriate command for install, build, or dev operations
 * @param name - Command type (install, build, dev)
 * @param pkg - Package.json contents
 * @param config - Build configuration
 * @param framework - Detected framework
 * @returns Command string or null
 */
function getCommand(
  name: 'install' | 'build' | 'dev',
  pkg: PackageJson | null,
  config: Config,
  framework: Framework | undefined
): string | null;

/**
 * Gets script name from package.json with fallbacks
 * @param pkg - Package.json contents
 * @param cmd - Base command name
 * @param config - Build configuration
 * @returns Script name to execute
 */
function getScriptName(pkg: PackageJson, cmd: string, config: Config): string;

/**
 * Checks if a script exists in package.json
 * @param script - Script name to check
 * @param pkg - Package.json contents
 * @returns Whether the script exists
 */
function hasScript(script: string, pkg: PackageJson): boolean;

Command Detection Priority:

Explicit Config: Use config.buildCommand, config.devCommand, config.installCommand
Package.json Scripts: Check for now-build, vercel-build, build, dev, now-dev
Framework Defaults: Use framework's default build/dev commands
Zero Config: Apply zero-configuration defaults

Example Command Resolution:

// For Next.js framework
const buildCommand = getCommand('build', pkg, config, nextjsFramework);
// Returns: "next build" (from framework defaults)

const devCommand = getCommand('dev', pkg, config, nextjsFramework);  
// Returns: "next dev" (from framework defaults)

Route Generation

Framework-specific route generation for single-page applications and static sites.

/**
 * Generates framework-specific routes for deployment
 * @param framework - Framework configuration
 * @param dirPrefix - Directory prefix for routes
 * @returns Promise resolving to route array
 */
async function getFrameworkRoutes(
  framework: Framework,
  dirPrefix: string
): Promise<Route[]>;

Framework Route Examples:

Next.js Routes:

[
  { src: '/api/(.*)', dest: '/api/$1' },
  { src: '/((?!api).+)', dest: '/$1.html' },
  { src: '/', dest: '/index.html' }
]

Gatsby Routes:

[
  { src: '/(.*)', dest: '/$1.html' },
  { src: '/', dest: '/index.html' }
]

Development Server Integration

Framework-specific development server handling with port management and proxy configuration.

Development Route Generation:

/**
 * Creates development route for proxying to local dev server
 * @param srcBase - Source base path
 * @param devPort - Development server port
 * @param route - Route configuration
 * @returns Route with dev server proxy destination
 */
const getDevRoute = (srcBase: string, devPort: number, route: RouteWithSrc): RouteWithSrc;

Development Flow:

Start framework's dev server on available port
Wait for server to become reachable
Generate proxy routes to development server
Handle process cleanup on termination

Example Dev Route:

{
  src: '/(.*)',
  dest: 'http://localhost:3000/$1'
}

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

tessl/npm-vercel--static-build