Quick Start - Deploy Your Site

s:CMS can be deployed to any static hosting platform. Choose your preferred option below.

GitHub Pages

Option 1: GitHub Actions (Recommended)

The template already ships a working workflow at .github/workflows/deploy.yml (Node 22, builds with npm run build, deploys dist/ via actions/deploy-pages). You normally only need to:

1. Configure your site URL in src/user.config.mjs:

   1
   export const userConfig = {
   2
     site: 'https://username.github.io/repo-name',
   3
     base: '/repo-name', // omit if deploying to a custom domain or a user/org root site
   4
   }

2. Enable GitHub Pages in repo settings:

   • Settings → Pages → Source: GitHub Actions

3. Push to GitHub - automatic deployment on every push

If you need to customize the workflow (different Node version, extra build steps, environment secrets), edit .github/workflows/deploy.yml directly — it’s a normal file in your repo, nothing special touches it.

Option 2: Manual Build & Deploy

1
npm run build
2
# Upload dist/ folder to GitHub Pages via gh-pages branch
3
npx gh-pages -d dist

Netlify

1. Connect your GitHub repository
2. Build settings:
   • Build command: npm run build
   • Publish directory: dist
3. Deploy

With Environment Variables:

1
[build]
2
  command = "npm run build"
3
  publish = "dist"
4

5
[build.environment]
6
  NODE_VERSION = "20"
7

8
# Optional: Set environment variables
9
# DIRECTUS_URL = "https://your-directus.com"
10
# DIRECTUS_TOKEN = "your-token"

Vercel

1. Import your GitHub repository
2. Framework Preset: Astro
3. Deploy

With Environment Variables:

1
{
2
  "buildCommand": "npm run build",
3
  "outputDirectory": "dist",
4
  "framework": "astro"
5
}

Add secrets in Vercel dashboard: Settings → Environment Variables

Cloudflare Pages

1. Connect your GitHub repository
2. Build settings:
   • Build command: npm run build
   • Build output directory: dist
3. Deploy

With Environment Variables: Add in Cloudflare dashboard: Settings → Environment variables

Traditional Hosting (FTP/SSH)

1
# Build locally
2
npm run build
3

4
# Upload dist/ folder to your server
5
# Via FTP, rsync, or your hosting panel

Managing Secrets & Environment Variables

If your site uses Directus, external APIs, or other services requiring credentials, never commit secrets to your repository.

Local Development

Create .env file (gitignored by default):

1
DIRECTUS_URL=https://your-directus-instance.com
2
DIRECTUS_TOKEN=your_secret_token
3
PUBLIC_SITE_URL=http://localhost:4321

Access in your code:

1
import.meta.env.DIRECTUS_URL
2
import.meta.env.DIRECTUS_TOKEN
3
import.meta.env.PUBLIC_SITE_URL // Available in client code

Deployment Platform Setup

GitHub Actions:

Add secrets to your repository:

1. Go to: Settings → Secrets and variables → Actions
2. Click “New repository secret”
3. Add your secrets (e.g., DIRECTUS_TOKEN)

Update your GitHub Actions workflow to use secrets:

1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    steps:
5
      # ... other steps ...
6

7
      - name: Build with Astro
8
        run: npm run build
9
        env:
10
          DIRECTUS_URL: ${{ secrets.DIRECTUS_URL }}
11
          DIRECTUS_TOKEN: ${{ secrets.DIRECTUS_TOKEN }}
12
          PUBLIC_SITE_URL: ${{ vars.PUBLIC_SITE_URL }}

Note: Use secrets for sensitive data, vars for non-sensitive configuration.

Platform-Specific Secrets

Netlify:

• Dashboard → Site settings → Environment variables
• Or via netlify.toml:

1
[context.production.environment]
2
  PUBLIC_SITE_URL = "https://yourdomain.com"

Vercel:

• Dashboard → Project Settings → Environment Variables
• Set for: Production, Preview, Development

Cloudflare Pages:

• Dashboard → Settings → Environment variables
• Separate settings for Production and Preview

Security Best Practices

1. ✅ Never commit .env files - Already in .gitignore
2. ✅ Use PUBLIC_ prefix for client-side variables only
3. ✅ Rotate secrets regularly - Especially after team changes
4. ✅ Use different secrets per environment - Production vs. Preview
5. ❌ Don’t log secrets - Be careful with console.log in production
6. ❌ Don’t expose server-side secrets - Keep them in .env, not in public code

Example: Directus Integration with Secrets

src/content.config.ts:

1
import { defineCollection } from 'astro:content';
2
import { directusLoader } from '@lad-sapienza/scms-core/integrations/directusLoader';
3

4
const articlesCollection = defineCollection({
5
  loader: directusLoader({
6
    url: import.meta.env.DIRECTUS_URL,
7
    token: import.meta.env.DIRECTUS_TOKEN,
8
    collection: 'articles',
9
  }),
10
});
11

12
export const collections = {
13
  articles: articlesCollection,
14
};

Required secrets:

• DIRECTUS_URL - Your Directus instance URL
• DIRECTUS_TOKEN - Static token with read permissions

Custom Build Scripts

Add to package.json:

1
{
2
  "scripts": {
3
    "build:prod": "astro check && astro build",
4
    "build:preview": "astro build --mode preview",
5
    "deploy": "npm run build && npx gh-pages -d dist"
6
  }
7
}

Continuous Deployment Options

Option 1: Direct Git Push

• GitHub Pages, Netlify, Vercel auto-deploy on git push

Option 2: GitHub Actions (Custom)

Create .github/workflows/deploy.yml with your platform-specific deployment

Option 3: Platform CLI

1
# Netlify
2
npm install -g netlify-cli
3
netlify deploy --prod
4

5
# Vercel
6
npm install -g vercel
7
vercel --prod

Troubleshooting Deployment

Build Fails

Check Node version:

1
- name: Setup Node
2
  uses: actions/setup-node@v4
3
  with:
4
    node-version: "20"  # Match your local version

Check dependencies:

1
rm -rf node_modules package-lock.json
2
npm install
3
npm run build

Site Shows 404

For GitHub Pages project sites, set base in astro.config.mjs:

1
export default {
2
  site: 'https://username.github.io',
3
  base: '/repo-name',
4
}

For custom domains, no base needed:

1
export default {
2
  site: 'https://yourdomain.com',
3
}

Environment Variables Not Working

• ✅ Restart dev server after adding .env
• ✅ Use PUBLIC_ prefix for client-side access
• ✅ Check variable names match exactly (case-sensitive)
• ✅ Verify secrets are set in deployment platform

Images Not Loading

Check image paths:

• Use /images/photo.jpg for files in public/images/
• Use relative paths ./photo.jpg for images next to content
• Astro optimizes images automatically

Performance Optimization

Build Optimization

1
export default {
2
  build: {
3
    inlineStylesheets: 'auto',
4
  },
5
  image: {
6
    service: {
7
      entrypoint: 'astro/assets/services/sharp',
8
    },
9
  },
10
}

Caching Strategy

For GitHub Actions:

1
- name: Setup Node
2
  uses: actions/setup-node@v4
3
  with:
4
    node-version: "20"
5
    cache: npm  # Caches node_modules

For Netlify/Vercel:

• Built-in caching enabled automatically
• Clear cache in settings if needed

Keeping s:CMS Up-to-Date

The s:CMS framework layer is the @lad-sapienza/scms-core npm package — updating it is an ordinary dependency update, not a custom script.

1
npm update @lad-sapienza/scms-core

Your content and customizations in src/ are never touched, because the framework was never part of this repository to begin with — it lives entirely in node_modules. See Updating for checking what’s new before you update.

Best Practices

1. Update regularly - Smaller updates are easier to review
2. Test locally - Always run npm run dev after updating
3. Read changelogs - Review what’s changing in each release

Need help? Check out docs/UPDATING.md for detailed instructions!