Configuration

Customize the SvelteKit Exec Adapter to fit your project’s needs.

Basic Configuration

The adapter accepts configuration options in your svelte.config.js:

import adapter from 'sveltekit-exec-adapter';

const config = {
	kit: {
		adapter: adapter({
			// Basic options
			out: 'build',
			binaryName: 'my-app',
			embedStatic: true,
			target: 'linux-x64',
			openBrowser: true
		})
	}
};

export default config;

Configuration Options

Basic Options

out

• Type: string
• Default: 'build'
• Description: Output directory for the build

adapter({
	out: 'dist' // Build output goes to ./dist/
});

binaryName

• Type: string
• Default: 'app'
• Description: Name of the generated executable

adapter({
	binaryName: 'my-awesome-app' // Creates my-awesome-app(.exe)
});

embedStatic

• Type: boolean
• Default: true
• Description: Whether to embed static assets in the binary

adapter({
	embedStatic: false // Static files served from filesystem
});

target

• Type: string
• Default: Auto-detected based on current platform
• Description: Target platform for the executable

Available targets:

• linux-x64
• linux-arm64
• darwin-x64 (macOS Intel)
• darwin-arm64 (macOS Apple Silicon)
• windows-x64

adapter({
	target: 'linux-x64' // Build for Linux 64-bit
});

volume

• Type: string
• Default: '/data'
• Description: Mount point for persistent data in containers

adapter({
	volume: '/app/data'
});

openBrowser

• Type: boolean
• Default: false
• Description: Automatically open the default browser when the server starts

adapter({
	openBrowser: true // Opens http://localhost:3000 automatically
});

Cross-platform support:

• Linux: Uses xdg-open
• macOS: Uses open
• Windows: Uses start

Note: If the browser command fails, the server will continue running normally and display a message asking you to open the browser manually.

Asset Validation Options

Control how the adapter handles and validates assets during build:

validation.maxAssetSize

• Type: number
• Default: 50 * 1024 * 1024 (50MB)
• Description: Maximum size for individual assets

validation.maxTotalSize

• Type: number
• Default: 500 * 1024 * 1024 (500MB)
• Description: Maximum total size of all assets

validation.warnThreshold

• Type: number
• Default: 10 * 1024 * 1024 (10MB)
• Description: Size threshold for warnings

validation.blockedExtensions

• Type: string[]
• Default: ['.exe', '.dll', '.so', '.dylib', '.app', '.deb', '.rpm']
• Description: File extensions that will cause build failures

validation.warnExtensions

• Type: string[]
• Default: ['.zip', '.tar', '.gz', '.rar', '.7z', '.iso', '.dmg']
• Description: File extensions that will trigger warnings

validation.allowedExtensions

• Type: string[]
• Default: undefined
• Description: If provided, only these extensions are allowed

validation.skip

• Type: boolean
• Default: false
• Description: Skip validation entirely (not recommended)

Complete Configuration Example

import adapter from 'sveltekit-exec-adapter';

const config = {
	kit: {
		adapter: adapter({
			// Basic configuration
			out: 'dist',
			binaryName: 'my-production-app',
			embedStatic: true,
			target: 'linux-x64',
			volume: '/app/data',
			openBrowser: true,

			// Asset validation
			validation: {
				maxAssetSize: 100 * 1024 * 1024, // 100MB per asset
				maxTotalSize: 1024 * 1024 * 1024, // 1GB total
				warnThreshold: 25 * 1024 * 1024, // Warn at 25MB

				// Custom file restrictions
				blockedExtensions: ['.exe', '.dll', '.malware'],
				warnExtensions: ['.zip', '.large-file'],

				// Allow only specific extensions
				allowedExtensions: [
					'.js',
					'.css',
					'.html',
					'.json',
					'.png',
					'.jpg',
					'.jpeg',
					'.gif',
					'.svg',
					'.woff',
					'.woff2',
					'.ttf',
					'.eot',
					'.ico',
					'.webp',
					'.avif'
				],

				// Enable validation (recommended)
				skip: false
			}
		})
	}
};

export default config;

Environment-Specific Configuration

Development

const isDev = process.env.NODE_ENV === 'development';

adapter({
	binaryName: isDev ? 'my-app-dev' : 'my-app',
	openBrowser: isDev, // Auto-open browser in development
	validation: {
		skip: isDev // Skip validation in development
	}
});

Production

adapter({
	embedStatic: true,
	openBrowser: false, // Don't auto-open in production
	validation: {
		maxAssetSize: 25 * 1024 * 1024, // Stricter limits for production
		maxTotalSize: 200 * 1024 * 1024,
		allowedExtensions: ['.js', '.css', '.png', '.svg', '.woff2']
	}
});

Cross-Platform Building

Build for multiple platforms in CI/CD:

# .github/workflows/build.yml
name: Build Executables
on: [push]

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            target: linux-x64
          - os: macos-latest
            target: darwin-x64
          - os: windows-latest
            target: windows-x64

    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
      - run: npm ci
      - run: npm run build
        env:
          TARGET: ${{ matrix.target }}

Performance Optimization

Reduce Binary Size

adapter({
	embedStatic: false, // Serve assets from filesystem
	validation: {
		maxAssetSize: 5 * 1024 * 1024, // 5MB limit
		allowedExtensions: ['.js', '.css', '.svg'] // Only essential files
	}
});

Optimize Assets

// Use with asset optimization tools
adapter({
	validation: {
		warnThreshold: 1 * 1024 * 1024, // 1MB warning
		blockedExtensions: ['.psd', '.ai', '.sketch'] // Block design files
	}
});

Troubleshooting Configuration

Common Issues

Build fails with asset too large:

adapter({
	validation: {
		maxAssetSize: 100 * 1024 * 1024 // Increase limit
	}
});

Binary too large:

adapter({
	embedStatic: false, // Don't embed assets
	validation: {
		allowedExtensions: ['.js', '.css'] // Only essential files
	}
});

Cross-platform issues:

adapter({
	target: process.env.TARGET || 'linux-x64' // Set via environment
});

Browser not opening automatically:

adapter({
	openBrowser: true // Enable auto-open
});

If the browser still doesn’t open:

• Check that you have a default browser set
• On Linux: Ensure xdg-open is available
• On macOS: Ensure open command works
• On Windows: Check that start command is available
• The server will display a manual URL if auto-open fails