Skateboard

a react starter with auth, stripe, shadcn, and sqlite

🎬 Demo

🚀 Quick Start

npx create-skateboard-app

That's it, your app is now running at http://localhost:5173 🎉

✨ What's Included

Everything you need to ship a production-ready app:

🏗️ Application Shell Architecture (v1.0)

• 95% less boilerplate - Focus on features, not infrastructure
• Shell + Content + Config - Framework provides structure, you provide content
• Update once, fix everywhere - All apps inherit improvements from skateboard-ui
• 16-line main.jsx - Just define your routes
• Convention over configuration - Sensible defaults with escape hatches everywhere

🔐 Authentication & User Management

• Sign up / Sign in with JWT tokens
• Protected routes with automatic redirects
• User context management across your app
• Session persistence with secure cookies
• App-specific auth isolation
• Usage tracking with configurable limits for free users

💳 Stripe Integration

• Checkout flows ready to go
• Subscription management portal
• Webhook handling for payment events
• Customer portal integration

🎨 Beautiful UI Components

• 50+ Shadcn/ui components pre-configured
• Dark/Light mode with system detection
• Mobile-ready design with responsive sidebar and TabBar
• Landing page that converts - fully customizable via constants.json
• Settings page with user management
• Legal pages (Terms, Privacy, EULA)

🛠️ Developer Experience

• Hot Module Replacement with Vite 7.1+
• Zero config - just works out of the box
• Multi-database support - SQLite (default), MongoDB, PostgreSQL
• constants.json - customize everything in one place
• Modern JavaScript - no TypeScript complexity
• Built-in hooks - useListData, useForm for common patterns
• API utilities - apiRequest with automatic auth and error handling

📖 Frontend Configuration

Update src/constants.json to customize your app:

{
  "appName": "Your App Name",
  "tagline": "Your Tagline", 
  "cta": "Get Started"
}

📖 Backend Configuration

Database Configuration - Update backend/config.json:

{
  "client": "http://localhost:5173",
  "database": {
    "db": "MyApp",
    "dbType": "sqlite",
    "connectionString": "./databases/MyApp.db"
  }
}

Update to backend/.env:

# Sqlite remove below
MONGODB_URL=mongodb+srv://user:[email protected]/
POSTGRES_URL=postgresql://user:pass@example-hostname:5432/myapp

Auth Variables - Update to backend/.env: enter a unique random string below

JWT_SECRET=your-secret-key
FREE_USAGE_LIMIT=20  # Optional: Monthly usage limit for free users (default: 20)

Supported Database Types:

• SQLite (default): "dbType": "sqlite"
• PostgreSQL: "dbType": "postgresql" with "connectionString": "${POSTGRES_URL}"
• MongoDB: "dbType": "mongodb" with "connectionString": "${MONGODB_URL}" with "db": "SkateboardApp"

💳 Stripe Setup

To enable payments, configure your Stripe products:

1. Create Product in Stripe Dashboard

   • Go to Product Catalog → Create Product
   • Add Name and Amount
   • Click More Pricing Options
   • Scroll to Lookup Key at bottom
   • Enter: my_lookup_key
   • This allows future pricing changes on stripe.com without updating your code

2. Update Environment Variables

   STRIPE_KEY=sk_live_your_secret_key

   Security Note: Use your secret key OR create a restricted key with these permissions:

   • Read/Write: Checkout Sessions
   • Read: Customers, Prices, Products

3. Setup Webhook

   • Go to stripe.com → Developers (lower left) → Webhooks
   • Click Add Endpoint
   • Add your endpoint URL: https://yourdomain.com/payment
   • Select these events:
     • customer.subscription.created - Customer signed up for new plan
     • customer.subscription.deleted - Customer's subscription ends
     • customer.subscription.updated - Subscription changes (plan switch, trial to active, etc.)
   • Copy the Signing Secret to your environment:

   STRIPE_ENDPOINT_SECRET=whsec_your_webhook_secret

🏗️ Tech Stack

Built with the latest and greatest:

Technology	Version	Purpose
React	v19	UI Framework
skateboard-ui	v1.0+	Application Shell Framework
Vite	v7.1+	Build Tool & Dev Server
Tailwind CSS	v4.1+	Styling
Shadcn/ui	Latest	Component Library
React Router	v7.8+	Routing
Express	v5	Backend Server
Multi-Database	Latest	SQLite, PostgreSQL, MongoDB
Stripe	Latest	Payments
JWT	Latest	Authentication

📚 Architecture

Skateboard uses an Application Shell Architecture where the framework (skateboard-ui) provides structure and your app provides content.

Your app in 3 parts:

1. Shell (skateboard-ui) - Routing, auth, context, utilities
2. Content (your code) - Components and business logic
3. Config (constants.json) - App-specific settings

Example main.jsx (complete app):

import { createSkateboardApp } from '@stevederico/skateboard-ui/App';
import constants from './constants.json';
import HomeView from './components/HomeView.jsx';

const appRoutes = [
  { path: 'home', element: <HomeView /> }
];

createSkateboardApp({ constants, appRoutes });

That's it! The shell handles routing, auth, layout, landing page, sign in/up, settings, payment, and all legal pages.

Learn more:

• Architecture Documentation - Deep dive into the shell pattern
• Migration Guide - Upgrade from 0.9.x to 1.0.0

🚀 Deployment

Choose your preferred deployment platform:

• Vercel - Deploy both frontend and backend together (recommended)
• Render - Separate frontend and backend services
• Netlify + Railway - Netlify frontend with Railway backend

Each guide includes complete step-by-step instructions, environment setup, and Stripe configuration.

🤝 Contributing

We love contributions!

# Fork the repo, then:
git clone https://github.com/YOUR_USERNAME/skateboard
cd skateboard
npm install
npm run start

📬 Community & Support

• 🐦 X: @stevederico
• 🐛 Issues: GitHub Issues

🙏 Acknowledgements

Built on the shoulders of giants:

• React - The library that powers the web
• Vite - Lightning fast build tool
• Tailwind CSS - Utility-first CSS
• Shadcn/ui - Beautiful components
• Stripe - Payment infrastructure

🎪 Related Projects

• skateboard-ui - Component library
• skateboard-blog - Blog template
• create-skateboard-app - CLI tool

🚀 Ready to Ship?

npx create-skateboard-app

📄 License

MIT License - use it however you want! See LICENSE for details.

---

Built with ❤️ by Steve Derico and contributors

⭐ Star us on GitHub — it helps!