Standaloner

Create self-contained, deployable Node.js applications by bundling your code and including necessary dependencies.

Features

• Deployment-ready output directory with all dependencies included
• Intelligent bundling with proper handling of native modules and dependencies
• Preserves file references (URLs, paths) and handles multiple dependency versions
• Vite integration via plugin

Installation

# npm
npm install standaloner

# yarn
yarn add standaloner

# pnpm
pnpm add standaloner

Usage

Basic Usage

import standaloner from 'standaloner';

// Single entry point
await standaloner({
  input: 'src/server.js',
  outDir: 'dist'
});

// Multiple entry points
await standaloner({
  input: ['src/server.js', 'src/workers/queue.js'],
  outDir: 'dist'
});

With Vite

// vite.config.js
import { defineConfig } from 'vite';
import standaloner from 'standaloner/vite';

export default defineConfig({
  plugins: [standaloner({
    // Options (all optional)
    bundle: false,     // Set to true to bundle into a single file
    minify: false,     // Set to true to minify output
    trace: true,       // Set to false to disable dependency tracing
    external: [],      // Array of packages to exclude from bundling
    isolated: false    // Set to true to build each entry separately without shared chunks
  })] // Uses Vite's build pipeline instead of Rolldown
});

Common Use Cases

• SSR Applications: Build with Vite and deploy the self-contained output
• Native Dependencies: Use modules that can't be bundled without special configuration
• Microservices: Create standalone deployable units for each service
• Serverless Functions: Build isolated, self-contained functions for Vercel, AWS Lambda, or similar platforms

Configuration Options

Option	Type	Default	Description
input	string | string[] | object	-	Input file(s) to process. Can be a single file path, array of paths, or object with named entries
outDir	string	'<inputDir>/dist'	Output directory
bundle	boolean | object	true	Bundle options or disable bundling. See Advanced Options for object properties
trace	boolean	true	Whether to trace dependencies
cleanup	boolean	false	Delete input files after processing
verbose	boolean	false	Enable verbose logging

Bundle Options

When bundle is an object, it supports these additional properties:

Property	Type	Default	Description
external	(string | RegExp)[]	[]	Packages to exclude from bundling
plugins	Plugin[]	[]	Rolldown plugins to apply
output	object	-	Rolldown output options (e.g., format, sourcemap)
isolated	boolean	false	Build each entry separately without shared chunks

Advanced Options

await standaloner({
  input: 'src/index.js',
  outDir: 'dist',
  bundle: {
    // Specify packages to exclude from bundling
    external: ['some-native-module', /^my-org-packages/],

    // Add Rolldown plugins
    plugins: [myPlugin()],

    // Output options
    output: { format: 'esm' },

    // Build each entry separately (useful for serverless functions)
    isolated: true
  }
});

Isolated Builds

For serverless deployments (e.g., Vercel, AWS Lambda) where each function must be completely self-contained:

await standaloner({
  input: {
    functionA: 'src/functionA.js',
    functionB: 'src/functionB.js',
    functionC: 'src/functionC.js'
  },
  outDir: 'dist',
  bundle: {
    isolated: true  // Each function becomes a standalone bundle without shared chunks
  }
});

When isolated: true:

• Each entry point is bundled separately
• No shared chunks are created between entry points
• Each output file is completely self-contained
• Builds run concurrently for better performance
• Ideal for serverless functions that need independent deployment

How It Works

1. Bundle & Relocate: Uses Rolldown to bundle code and relocate referenced files to .static (or Vite's build pipeline when using the Vite plugin)
2. Trace: Uses Vercel's Node File Trace to detect dependencies that can't be bundled
3. Organize: Copies dependencies to output with proper node_modules structure

License

MIT