Installation

Installation Guide

This guide covers different ways to install and set up astro-basics depending on your use case.

System Requirements

Node.js: Version 18 or higher
npm: Version 8 or higher (or yarn/pnpm equivalent)
Git: For cloning the repository

Installation Options

Full Project Setup

For complete project with all features, examples, and development tools:

# Clone the repository
git clone https://github.com/shawn-sandy/astro-basics.git

# Navigate to project directory
cd astro-basics

# Install dependencies (takes ~4 minutes)
npm install

# Set up environment
cp .env.example .env

# Install pre-commit hooks
npm run prepare

# Install Playwright browsers (for E2E tests)
npx playwright install

Component Library Only

To use astro-basics components in an existing Astro project:

npm install astro-basics-website

Post-Installation Setup

1. Environment Configuration

Edit your .env file with the required keys:

# Authentication (Required)
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
CLERK_SECRET_KEY=sk_test_your_key_here

# Site URL
SITE_URL=http://localhost:4321

# Database (Optional)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Turso (Optional)
TURSO_DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your_auth_token_here

2. Database Setup (Optional)

The project supports Supabase (PostgreSQL) and Turso (LibSQL) backends.

Interactive Setup (Recommended)

# Use the database wizard for guided setup
npm run db:wizard

The wizard will detect available credentials and guide you through configuration.

Manual Setup

# Check database status and configuration
npm run db:status

# Initialize database schema
npm run db:setup

# Verify connection
npm run db:check

# Run migrations (Supabase)
npm run db:migrate

# Check migration status
npm run db:migrate:status

Database Switching

The project includes seamless database switching with automatic backups:

# Switch to Supabase (with backup)
npm run db:switch:supabase

# Switch to Turso (with backup)
npm run db:switch:turso

# Auto-detect and use available database
npm run db:switch:auto

# Create backup only
npm run db:backup

# Restore from backup
npm run db:restore

See the Complete Setup Guide and Database Switching Guide for detailed configuration.

3. Role Configuration (Optional)

The project includes a configurable role system for managing user permissions and access control.

Default Roles

By default, astro-basics comes with a 3-tier role system:

member (Level 1) - Default role for new users
admin (Level 2) - Administrative access
super_admin (Level 3) - Full system control

These roles are ready to use without any configuration.

Customizing Roles

If you need custom roles for your application (e.g., author, moderator, editor):

1. Edit the configuration file:

vim config/roles.config.ts

2. Add or modify roles:

export const roleConfig: RoleConfig = {
  roles: [
    { name: 'member', level: 1, label: 'Member' },
    { name: 'author', level: 2, label: 'Author' },      // Custom
    { name: 'moderator', level: 3, label: 'Moderator' }, // Custom
    { name: 'admin', level: 4, label: 'Admin' },
    { name: 'super_admin', level: 5, label: 'Super Admin' },
  ],
  coreRoles: ['member', 'admin', 'super_admin'],
}

3. Generate types and migrations:

# Generate TypeScript types and database migrations
npm run setup:roles

# Apply the migration
npm run db:migrate

4. Commit your changes:

git add config/ src/types/ scripts/migrations/
git commit -m "Configure custom roles"

See the Complete Setup Guide - Role Configuration and Configurable Roles Guide for detailed instructions and templates.

4. Verify Installation

Start the development server:

npm run start

Visit http://localhost:4321 to see your site running.

Development Tools

Code Quality

# Run all linting and formatting
npm run fix:all

# Type checking
npm run type-check

# Individual tools
npm run lint          # ESLint
npm run lint:styles   # StyleLint
npm run format        # Prettier

Testing

# Unit tests
npm test

# E2E tests
npm run test:e2e

# Test reports
npm run test:e2e:report

Build and Deploy

# Production build
npm run build

# Preview build
npm run preview

# Deploy to Netlify
npm run deploy:prod

Component Usage

In Astro Files

---
import { Header, Footer } from 'astro-basics-website'
---

<Header title="My Site" />
<main>
  <!-- Your content -->
</main>
<Footer />

With TypeScript

import type { Props } from 'astro-basics-website'

// Use component props with full type safety

Troubleshooting

Common Issues

1. Installation takes too long

Expected: npm install takes ~4 minutes
Warnings during installation are normal

2. Authentication errors

Ensure PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY are set
Use dummy keys for build-only testing

3. E2E tests failing

Run npx playwright install to install browsers
Ensure dev server is running on port 4321

4. Build warnings

getStaticPaths warnings in dynamic pages are expected
These don’t affect functionality

Getting Help

Check the GitHub Issues
Review the troubleshooting section (coming soon)
Ensure you’re using the latest version

Next Steps

After installation, explore these guides:

Complete Setup - Full feature configuration (database, roles, security)
Configurable Roles - Custom role system with templates and examples
Role Guard Usage - Access control patterns and best practices
Database Switching - Flexible backend selection
Components - Explore available components