Deployment Configuration

The deployment section tells Specra how to build your documentation for different hosting platforms. This ensures assets load correctly and your site works wherever you deploy it.

Why Deployment Configuration Matters

Different platforms serve your site from different URLs:

• Vercel: yoursite.vercel.app (serves from root /)
• GitHub Pages (no custom domain): username.github.io/repo-name (serves from /repo-name/)
• Netlify: yoursite.netlify.app (serves from root /)

Specra needs to know your deployment target to configure asset paths correctly.

Basic Configuration

1{
2  "deployment": {
3    "target": "vercel"
4  }
5}

That's all you need for most deployments. Specra handles the rest automatically.

Complete Configuration

1{
2  "deployment": {
3    "target": "vercel",
4    "basePath": "",
5    "customDomain": false
6  }
7}

Configuration Options

target

Type: string Default: "vercel"

Your deployment platform. This determines which build process Specra uses.

Available targets:

1{
2  "deployment": {
3    "target": "vercel"
4  }
5}

Options:

• "vercel" - Vercel, Railway, Render, or any Node.js hosting
• "github-pages" - GitHub Pages without custom domain
• "static" - Static hosting (Netlify, Cloudflare Pages)
• "custom-domain-static" - GitHub Pages with custom domain

basePath

Type: string Default: ""

Base path for your site. Only needed for GitHub Pages without a custom domain.

1{
2  "deployment": {
3    "target": "github-pages",
4    "basePath": "my-repo"
5  }
6}

When to use basePath:

✅ GitHub Pages without custom domain

URL: username.github.io/my-repo
Config: "basePath": "my-repo"

❌ GitHub Pages with custom domain

URL: docs.example.com
Config: "basePath": ""

❌ Vercel, Netlify, etc.

URL: yoursite.vercel.app
Config: "basePath": ""

customDomain

Type: boolean Default: false

Set to true when using a custom domain with GitHub Pages.

1{
2  "deployment": {
3    "target": "github-pages",
4    "customDomain": true,
5    "basePath": ""
6  }
7}

This tells Specra to serve assets from the root / instead of /repo-name/.

Platform-Specific Configurations

Vercel

Default configuration works perfectly:

1{
2  "deployment": {
3    "target": "vercel"
4  }
5}

Build command: npm run build Output: `directory No basePath needed

GitHub Pages (No Custom Domain)

For username.github.io/repo-name:

1{
2  "deployment": {
3    "target": "github-pages",
4    "basePath": "repo-name",
5    "customDomain": false
6  }
7}

Build command: npm run build:export Output: out directory Assets load from: /repo-name/_app/immutable/...

GitHub Pages (With Custom Domain)

For docs.example.com:

1{
2  "deployment": {
3    "target": "custom-domain-static",
4    "basePath": "",
5    "customDomain": true
6  }
7}

Also add public/CNAME:

docs.example.com

Build command: npm run build:export Output: out directory Assets load from: /_app/immutable/...

Netlify

1{
2  "deployment": {
3    "target": "static"
4  }
5}

Build command: npm run build:export Output: out directory No basePath needed

Cloudflare Pages

Same as Netlify:

1{
2  "deployment": {
3    "target": "static"
4  }
5}

How It Works

Build Modes

Specra has two build modes:

1. Standalone (Node.js hosting)

• Used for: Vercel, Railway, Render
• Command: npm run build
• Output: `directory
• Runs as Node.js server
• Supports dynamic features

2. Static Export (Static hosting)

• Used for: GitHub Pages, Netlify, Cloudflare Pages
• Command: npm run build:export
• Output: out directory
• Pure HTML/CSS/JS files
• No server required

The deployment.target determines which mode to use.

Asset Path Resolution

Specra uses the getAssetPath() utility to handle asset URLs:

1// Automatically adjusts based on deployment config
2getAssetPath('/images/logo.png')
3 
4// Vercel: /images/logo.png
5// GitHub Pages (no custom domain): /repo-name/images/logo.png
6// GitHub Pages (custom domain): /images/logo.png

You don't need to worry about this - Specra handles it automatically based on your config.

Switching Platforms

From Vercel to GitHub Pages

1. Update config:

1{
2  "deployment": {
3    "target": "github-pages",
4    "basePath": "your-repo-name"
5  }
6}

2. Change build command:

1npm run build:export  # instead of npm run build

3. Deploy out/ folder instead of .svelte-kit/

From GitHub Pages to Netlify

1. Update config:

1{
2  "deployment": {
3    "target": "static",
4    "basePath": ""
5  }
6}

2. Keep using npm run build:export

3. Netlify serves from root, so remove basePath

Testing Locally

Test Static Export

1npm run build:export
2npx serve out

Open the URL shown (usually http://localhost:3000). Verify:

• Pages load correctly
• Images appear
• Links work
• Navigation functions

Test with basePath

If using basePath, test locally with a server that respects it:

1npm run build:export
2npx serve out -s -p 3000

Then visit http://localhost:3000/your-repo-name to simulate GitHub Pages.

Troubleshooting

Assets Return 404

Check basePath matches repo name:

1{
2  "deployment": {
3    "basePath": "exact-repo-name"  // Must match exactly
4  }
5}

Verify you're using the right build command:

• GitHub Pages: npm run build:export (not npm run build)
• Vercel: npm run build (not npm run build:export)

Blank Page After Deploy

Check target is correct:

• GitHub Pages needs "target": "github-pages"
• Netlify needs "target": "static"
• Vercel needs "target": "vercel"

Verify deployment settings match config:

• Output directory should match build mode
• Build command should match target

Custom Domain Not Working

Ensure customDomain is true:

1{
2  "deployment": {
3    "customDomain": true,
4    "basePath": ""
5  }
6}

Check CNAME file exists:

• Must be in public/CNAME
• Contains only your domain
• No protocol, no trailing slash

Best Practices

Keep config in version control - Commit specra.config.json so deployments are consistent

Test locally before deploying - Use npx serve out to test static exports

Use environment-specific configs - Different configs for staging and production if needed

Document your setup - Add deployment instructions to your README

Verify after switching platforms - Test everything works when changing deployment targets

Next Steps