Technical Reference

Configuration Reference

Complete reference for all configuration files and options.

Configuration files

Installation configuration is split across multiple files for different concerns.

File	Purpose	Format
`astro.config.mjs`	Astro framework configuration	JavaScript
`tailwind.config.mjs`	Tailwind CSS customization	JavaScript
`components.json`	shadcn/ui component config	JSON
`tsconfig.json`	TypeScript compiler options	JSON
`.env`	Environment variables (development)	Key-value
`.env.production`	Environment variables (production)	Key-value
`docker-compose.yml`	Container orchestration base	YAML
`docker-compose.dev.yml`	Development overrides	YAML
`docker-compose.prod.yml`	Production overrides	YAML

astro.config.mjs

Core Astro configuration including integrations, build options, and server settings.

Complete configuration

 astro.config.mjs 
 import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
import icon from 'astro-icon';
import AstroPWA from '@vite-pwa/astro';

export default defineConfig({
  // Integrations
  integrations: [
    react(),
    tailwind({ applyBaseStyles: false }),
    icon(),
    AstroPWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'Installation Name',
        short_name: 'Installation',
        theme_color: '#d4a017',
        icons: [
          {
            src: '/icon-192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: '/icon-512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      }
    })
  ],

  // Output mode
  output: 'static',

  // Base path (if deploying to subdirectory)
  base: '/',

  // Build options
  build: {
    assets: '_astro'
  },

  // Development server
  server: {
    port: 4321,
    host: '0.0.0.0'
  },

  // Vite configuration
  vite: {
    ssr: {
      noExternal: ['@astrojs/react']
    },
    server: {
      hmr: {
        host: import.meta.env.PUBLIC_DOMAIN || 'localhost',
        protocol: 'wss',
        clientPort: 443
      }
    }
  },

  // View Transitions
  experimental: {
    viewTransitions: true
  },

  // Disable telemetry
  telemetry: false,
  devToolbar: { enabled: false }
}); 

Key options

Option	Type	Description
`output`	'static' \| 'server'	Build mode (static SSG or SSR)
`base`	string	Base path for deployment subdirectory
`server.port`	number	Development server port
`server.host`	string	Bind address (0.0.0.0 for Docker)
`telemetry`	boolean	Disable Astro telemetry

tailwind.config.mjs

Tailwind CSS theme customization including colors, fonts, and design tokens.

Complete configuration

 tailwind.config.mjs 
 /** @type {import('tailwindcss').Config} */
export default {
  darkMode: ['class'],
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        'atelier-cream': '#faf7f0',
        'atelier-ink': '#2d2d2d',
        'atelier-surface': '#f5f1e8',
        'craft-accent': '#d4a017',
        'craft-highlight': '#6b8e6b',
        'craft-emphasis': '#c65d4a',
        'craft-muted': '#8b7355',
      },
      fontFamily: {
        serif: ['Playfair Display', 'Georgia', 'serif'],
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
      borderRadius: {
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)',
      },
    },
  },
  plugins: [require('tailwindcss-animate'), require('@tailwindcss/typography')],
}; 

Custom colors

Color	Hex	Usage
`craft-accent`	#d4a017	Experience quadrant, primary accents
`craft-highlight`	#6b8e6b	Process quadrant, success states
`craft-emphasis`	#c65d4a	Craft quadrant, important elements
`craft-muted`	#8b7355	Philosophy quadrant, subtle elements
`atelier-cream`	#faf7f0	Light background, cards
`atelier-ink`	#2d2d2d	Dark text, headings

tsconfig.json

TypeScript compiler options and path aliases.

Configuration

 tsconfig.json 
 {
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "react",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "resolveJsonModule": true
  }
} 

Path aliases

Use @/ prefix for imports from src/ directory:

 import Button from '@/components/ui/button';
import { cn } from '@/lib/utils';
import type { User } from '@/types/user'; 

components.json

shadcn/ui configuration for component installation and styling.

Configuration

 components.json 
 {
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.mjs",
    "css": "src/styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
} 

Key options

Option	Value	Description
`style`	default	Component style variant
`rsc`	false	React Server Components (not used with Astro)
`tsx`	true	Use TypeScript
`cssVariables`	true	Use CSS variables for theming

Docker Compose

Container orchestration configuration for development and production.

Base configuration

 docker-compose.yml 
 services:
  web:
    build:
      context: .
      target: ${ATELIER_MODE:-dev}
    environment:
      - ATELIER_MODE=${ATELIER_MODE:-dev}
      - PUBLIC_DOMAIN=${PUBLIC_DOMAIN}
      - ENABLE_HMR=${ENABLE_HMR:-true}
    networks:
      - caddy

networks:
  caddy:
    external: true 

Development overrides

 docker-compose.dev.yml 
 services:
  web:
    command: npm run dev
    volumes:
      - ./src:/app/src
      - ./public:/app/public
      - ./astro.config.mjs:/app/astro.config.mjs
    ports:
      - "4321:4321" 

Production overrides

 docker-compose.prod.yml 
 services:
  web:
    command: node dist/server/entry.mjs
    labels:
      caddy: ${PUBLIC_DOMAIN}
      caddy.reverse_proxy: "{{upstreams 4321}}"
      caddy.tls.dns: cloudflare
      caddy.encode: gzip
    restart: unless-stopped 

CSS variables (globals.css)

Design tokens defined as CSS custom properties for consistent theming.

Color variables

 globals.css 
 @layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 0 0% 15%;
    --card: 0 0% 98%;
    --card-foreground: 0 0% 15%;
    --border: 0 0% 90%;
    --muted: 0 0% 96%;
    --muted-foreground: 0 0% 45%;
    --accent: 43 85% 46%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 0 0% 10%;
    --foreground: 0 0% 98%;
    --card: 0 0% 12%;
    --card-foreground: 0 0% 98%;
    --border: 0 0% 20%;
    --muted: 0 0% 15%;
    --muted-foreground: 0 0% 65%;
  }
} 

Using CSS variables

 <!-- Tailwind classes using variables -->
<div class="bg-background text-foreground border-border">
  <p class="text-muted-foreground">Content</p>
</div>

/* Custom CSS */
.custom-element {
  background: hsl(var(--background));
  color: hsl(var(--foreground));
  border-radius: var(--radius);
} 

PWA configuration

Progressive Web App manifest and service worker settings.

Manifest configuration

 // In astro.config.mjs
AstroPWA({
  registerType: 'autoUpdate',
  manifest: {
    name: 'Installation Full Name',
    short_name: 'Installation',
    description: 'Installation description',
    theme_color: '#d4a017',
    background_color: '#faf7f0',
    display: 'standalone',
    orientation: 'portrait',
    scope: '/',
    start_url: '/',
    icons: [
      {
        src: '/icon-192.png',
        sizes: '192x192',
        type: 'image/png',
        purpose: 'any maskable'
      },
      {
        src: '/icon-512.png',
        sizes: '512x512',
        type: 'image/png',
        purpose: 'any maskable'
      }
    ]
  },
  workbox: {
    navigateFallback: '/404',
    globPatterns: ['**/*.{css,js,html,svg,png,woff,woff2}']
  },
  devOptions: {
    enabled: true
  }
}) 

Manifest options

Option	Type	Description
`name`	string	Full application name
`short_name`	string	Short name for home screen
`theme_color`	string	Browser UI color
`display`	string	Display mode: standalone, fullscreen, minimal-ui
`orientation`	string	Screen orientation: portrait, landscape, any