bantam.hostbantam.host
Back to all frameworks
CLI Guide

Deploy Astro with Bantam CLI

Deploy content-focused Astro sites with zero JavaScript by default

Install Bantam CLI:

npm install -g @bantamhq/cli

View on NPM: @bantamhq/cli

Quick start:

# Build your Astro app
npm run build

# Deploy it
bantam deploy ./dist

Quick Start

1

Build your Astro site

Astro generates static HTML with minimal JavaScript

npm run build
Creates optimized files in ./dist directory
2

Preview the build (optional)

Test your production build locally

npm run preview
3

Deploy with Bantam

Your Astro site is live!

bantam deploy ./dist
Use --permanent for a permanent URL

Framework Details

Static Site Configuration

Astro is static by default. Ensure you're not using SSR features:

astro.config.mjs - Static output:

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Default is 'static' - perfect for Bantam
  output: 'static',
  
  // Configure build output
  build: {
    // Change output directory if needed
    // outDir: './build',
    
    // Configure asset handling
    assets: '_astro',
  }
});
If you have output: 'server' or output: 'hybrid', you'll need server-side hosting. Use output: 'static' for Bantam.

Site & Base Configuration

Configure your site URL and base path:

Set site URL for proper asset paths:

export default defineConfig({
  site: 'https://mysite.bantam.site',
  
  // If deploying to a subdirectory
  base: '/my-project',
  
  // For root deployment (default)
  base: '/',
});
The site config helps with generating correct URLs for sitemaps, RSS feeds, and canonical URLs.

Image Optimization

Astro's image optimization works great with static builds:

Using Astro's Image component:

---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.png';
---

<!-- Astro optimizes this at build time -->
<Image 
  src={heroImage} 
  alt="Hero" 
  width={1200}
  height={600}
  format="webp"
/>

<!-- For remote images -->
<Image 
  src="https://example.com/image.jpg" 
  alt="Remote" 
  width={800} 
  height={400}
  inferSize
/>
Images are optimized during build, creating multiple formats and sizes for better performance.

Framework Integration

Astro can use components from other frameworks:

Add framework integrations:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import vue from '@astrojs/vue';
import svelte from '@astrojs/svelte';

export default defineConfig({
  integrations: [
    react(),
    vue(),
    svelte(),
  ],
  
  // Control when JS loads
  experimental: {
    clientPrerender: true,
  }
});
Components are rendered to HTML at build time. Client-side JS only loads when usingclient:* directives.

Advanced Usage

Custom Domain

Deploy directly to your own domain

bantam deploy ./dist --domain myapp.com

Permanent Deployment

Keep your site online forever (requires login)

bantam deploy ./dist --permanent

Custom Expiry

Set how long your deployment stays online

bantam deploy ./dist --expiry-days 7

Custom Subdomain

Choose your own subdomain on bantam.site

bantam deploy ./dist --subdomain my-project

CI/CD Integration

Add Bantam to your continuous deployment pipeline:

# GitHub Actions example
- name: Deploy to Bantam
  run: |
    npm install -g @bantamhq/cli
    bantam login --token ${{ secrets.BANTAM_TOKEN }}
    bantam deploy ./dist --domain myapp.com --permanent
Troubleshooting

Common Issues & Solutions

Quick fixes for deployment challenges

01.404 errors on routes after deployment

For pretty URLs and client-side routing, create a public/_redirects file:

# Handle SPA-style routing
/*    /index.html   200

# Or for specific routes
/api/*  https://api.example.com/:splat  200
/blog   /blog/index.html               200

For Astro's file-based routing, this usually isn't needed unless using View Transitions.

02.Images not loading in production

Ensure you're importing images correctly for Astro to process them:

---
// ✅ Correct - Astro processes the image
import logo from '../images/logo.png';

// ❌ Wrong - Image won't be optimized
const logo = '/images/logo.png';
---

<img src={logo.src} alt="Logo" />

<!-- Or use Image component -->
<Image src={logo} alt="Logo" />

03.Build fails with 'Cannot find package' errors

Astro requires specific Node versions. Check compatibility:

# Check Node version
node --version

# Astro 3.x requires Node 18.14.1+
# Astro 4.x requires Node 18.17.1+

# Use nvm to switch versions
nvm use 18
npm install
npm run build

04.How to handle environment variables?

Astro uses Vite's env variable system:

# .env
PUBLIC_API_URL=https://api.example.com
SECRET_KEY=only-available-server-side

---
// In .astro files
const apiUrl = import.meta.env.PUBLIC_API_URL;

// In astro.config.mjs
console.log(import.meta.env.SECRET_KEY); // Build-time only
---

Only PUBLIC_ prefixed variables are exposed to client-side code.

05.Large JavaScript bundles with framework components

Control when framework components load their JavaScript:

<!-- Only HTML, no JS -->
<ReactComponent />

<!-- Load JS immediately -->
<ReactComponent client:load />

<!-- Load JS on idle -->
<ReactComponent client:idle />

<!-- Load JS when visible -->
<ReactComponent client:visible />

<!-- Load JS on media query -->
<ReactComponent client:media="(max-width: 768px)" />

Use client:visible or client:idle for better performance.