Getting Started

Getting Started with Astro-Basics

Welcome to astro-basics! This guide will help you get up and running with our component library and development framework.

What is Astro-Basics?

Astro-basics is a production-ready web development framework built on Astro that provides:

• Component Library: Reusable Astro and React components
• Authentication: Pre-configured Clerk integration with protected routes
• Database Support: Supabase (PostgreSQL) and Turso (LibSQL) with seamless switching
• Role System: Configurable user roles with TypeScript type safety
• Security Features: CSRF protection, rate limiting, RLS policies
• Styling System: SCSS-based design tokens and utilities
• Testing Suite: Unit and E2E testing with Vitest and Playwright
• PWA Ready: Progressive Web App capabilities with offline support

Prerequisites

Before you begin, make sure you have:

• Node.js 18 or higher
• npm or your preferred package manager
• Basic knowledge of Astro and React

Installation Methods

Option 1: Clone the Repository

For a complete setup with all features:

git clone https://github.com/shawn-sandy/astro-basics.git
cd astro-basics
npm install

Option 2: Use as Package (Component Library)

To use just the components in your existing project:

npm install astro-basics-website

Then import components:

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

<Header title="My Site" />

Environment Setup

1. Copy environment template:

   cp .env.example .env

2. Configure required variables:

   # Required for authentication
   PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
   CLERK_SECRET_KEY=sk_test_...
   
   # Optional: Database configuration
   SUPABASE_URL=https://...
   SUPABASE_ANON_KEY=eyJ...
   
   # Optional: Turso configuration
   TURSO_DATABASE_URL=libsql://...
   TURSO_AUTH_TOKEN=...

Development Commands

Start the development server:

# Recommended: Start dev server with SCSS watching
npm run start

# Or just the Astro dev server
npm run dev

Build for production:

npm run build

Run tests:

# Unit tests
npm test

# E2E tests (requires: npx playwright install)
npm run test:e2e

Setup Options

Choose your setup path based on your needs:

Quick Start (5 Minutes)

For minimal setup to start exploring:

1. Clone and install dependencies
2. Configure Clerk authentication
3. Start development server

👉 See Installation Guide for quick setup.

Complete Setup (Full Features)

For production-ready setup with all features:

1. Authentication - Clerk integration with protected routes
2. Database - Supabase (PostgreSQL) or Turso (LibSQL) with seamless switching
3. Role Configuration - Customizable user roles with TypeScript type safety
4. Security Features - CSRF protection, rate limiting, RLS policies

👉 See Complete Setup Guide for comprehensive configuration.

Next Steps

After setup, explore these guides:

Core Setup Guides

1. Complete Setup - Comprehensive configuration (auth, database, roles, security)
2. Installation - Quick installation and basic setup

Role & Access Control

3. Configurable Roles - Custom role system with templates and examples
4. Role Guard Usage - Access control patterns and best practices

Advanced Features

5. Database Switching - Seamless backend provider switching
6. Components - Component library reference
7. API Reference - Detailed API documentation

Getting Help

• GitHub Issues: Report bugs or request features
• Documentation: Browse this guide for detailed information
• Examples: Check the /src/pages/ directory for usage examples