Skip to content

README.md

Latest commit

 

History

History
192 lines (128 loc) · 6.13 KB

README.md

File metadata and controls

192 lines (128 loc) · 6.13 KB
Raw

10x Astro Starter

A modern, opinionated starter template for building fast, accessible web applications.

Tech Stack

  • Astro v7 - Modern web framework with server-first rendering
  • React v19 - UI library for interactive components
  • TypeScript v6 - Type-safe JavaScript
  • Tailwind CSS v4 - Utility-first CSS framework
  • Supabase - Authentication and backend-as-a-service
  • Cloudflare Workers - Edge deployment runtime

Prerequisites

  • Node.js v22.14.0 (as specified in .nvmrc)
  • npm (comes with Node.js)

Getting Started

  1. Clone the repository:
git clone https://github.com/przeprogramowani/10x-astro-starter.git
cd 10x-astro-starter
  1. Install dependencies:
npm install

  1. Set up Supabase and configure environment variables — see Supabase Configuration below.

  2. Create a .dev.vars file for local Cloudflare dev secrets:

cp .env.example .dev.vars
  1. Run the development server:
npm run dev

Available Scripts

  • npm run dev - Start development server (Cloudflare workerd runtime)
  • npm run build - Build for production
  • npm run preview - Preview production build
  • npm run lint - Run ESLint with type-checked rules
  • npm run lint:fix - Auto-fix ESLint issues
  • npm run format - Run Prettier
  • npm run smoke - Smoke test the auth flow against a running server (BASE_URL, defaults to http://localhost:4321)

Project Structure

.
├── src/
│ ├── layouts/ # Astro layouts
│ ├── pages/ # Astro pages
│ │ └── api/ # API endpoints
│ ├── components/ # UI components (Astro & React)
│ └── assets/ # Static assets
├── public/ # Public assets
├── wrangler.jsonc # Cloudflare Workers config

Supabase Configuration

This project uses Supabase for authentication. Environment variables are declared via Astro's astro:env schema and are treated as server-only secrets — they are never exposed to the client.

First-time setup (local, no cloud project needed)

Requires Docker and ~7 GB RAM.

  1. Create your .env file:
cp .env.example .env
  1. Initialize the local Supabase project (creates a supabase/ config folder):
npx supabase init
  1. Start the local stack (downloads Docker images on first run):
npx supabase start
  1. Copy the credentials printed by the CLI into your .env and .dev.vars:
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_KEY=<anon key from CLI output>
  1. To stop the stack when done:
npx supabase stop

The local Studio UI is available at http://localhost:54323.

No database tables or migrations are required — this project uses Supabase Auth's built-in auth.users table only.

Using a cloud Supabase project instead

If you prefer to use a hosted Supabase project, add these variables to your .env and .dev.vars files:

Variable Description
SUPABASE_URL Project URL from Supabase dashboard → Settings → API
SUPABASE_KEY anon public key from Supabase dashboard → Settings → API 
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_KEY=<anon-key>

Email confirmation in local development

By default Supabase requires email confirmation before a user can sign in. To skip this during local development:

  1. Open the Supabase dashboard for your project
  2. Go to Authentication → Email → Confirm email
  3. Toggle it off

Users can then sign in immediately after sign-up without clicking a confirmation link.

Auth routes

Route Description
/auth/signin Email/password sign-in form
/auth/signup Email/password sign-up form
/auth/confirm-email Post-signup "check your inbox" page
/dashboard Example protected page (redirects to /auth/signin if unauthenticated)

Route protection is handled in src/middleware.ts. Add paths to the PROTECTED_ROUTES array there to require authentication.

Deployment

This project deploys to Cloudflare Workers.

  1. Build the project:
npm run build
  1. Deploy with Wrangler:
npx wrangler deploy

Set SUPABASE_URL and SUPABASE_KEY as secrets in your Cloudflare dashboard or via npx wrangler secret put.

Smoke test

scripts/smoke.mjs is a dependency-free Node script that walks the whole auth flow (sign-up, sign-in, protected page, sign-out) over HTTP. Run it against the dev server or the production preview after dependency upgrades:

npm run dev            # or: npm run build && npm run preview
BASE_URL=http://localhost:4321 npm run smoke

It needs a reachable Supabase instance (local or cloud) with email confirmation disabled.

Note: this script exists primarily to guard the development of the starter itself — it is a fast sanity check that dependency upgrades did not break the build, the Cloudflare adapter or the Supabase auth flow. It is not a substitute for a real test suite. Once you build your own product on top of this starter, add proper tests (unit, integration, end-to-end) suited to your application.

CI

GitHub Actions runs two jobs on every push and PR to master:

  • ci — lint, astro check and build. Configure SUPABASE_URL and SUPABASE_KEY as repository secrets for the build step.
  • smoke — starts a local Supabase via the Supabase CLI, builds, serves the production preview on the Cloudflare runtime and runs npm run smoke against it. No secrets required.

License

MIT