Full-Stack Web App Boilerplate with Auth & Payments – Catalyst Starter Kit

Catalyst Starter Kit is a pre-configured boilerplate for building modern, full-stack web applications.

It is built on a foundation of Bun.js, a fast JavaScript runtime, and Next.js, a React framework for server-side rendering.

For the backend, it uses Prisma as its ORM for simplified database interactions. The frontend is constructed with Tailwind CSS and shadcn/ui components for a utility-first approach to styling.

Features

Use Cases

• SaaS Application Development – Build subscription-based software with user authentication, billing, and payment processing already configured.
• E-commerce Platform Creation – Launch online stores with Stripe integration, user accounts, and order management capabilities.
• Corporate Web Applications – Develop internal tools and dashboards with enterprise-grade authentication and database management.
• Content Management Systems – Create custom CMS platforms with user roles, content publishing, and SEO optimization features.
• API-First Applications – Build modern web services with Next.js API routes, database integration, and comprehensive logging.

How to Use It

1. Installing Bun.js:

# For macOS and Linux
curl -fsSL https://bun.sh/install | bash
# For Windows
powershell -c "irm bun.sh/install.ps1 | iex"

2. Clone or download the Catalyst Starter Kit repository from GitHub.

git clone https://github.com/kovrichard/catalyst.git

3. Navigate to the project directory and copy the environment configuration file:

cp .env.sample .env

4. Install all project dependencies using Bun:

bun install

5. The starter kit uses PostgreSQL as the default database engine with Prisma as the ORM. Set up a local development database using Docker:

docker compose up -d

This command launches a PostgreSQL container in the background. The database connection details are pre-configured in the .env file with the following default settings:

DATABASE_URL="postgresql://app_dev:password@localhost:5432/dev"

6. Generate the Prisma client and run database migrations:

bun run migrate

7. Connect to your database for direct management:

# Using Docker Compose
docker compose exec database psql -U app_dev -d dev
# Or using Make (if installed)
make db

8. Configure the authentication system by updating your .env file with the required secrets. The starter kit comes with a development secret pre-configured:

AUTH_SECRET="your-development-secret-here"

9. For production deployments, generate a secure random string for this value. Add OAuth provider credentials if needed:

# GitHub OAuth
AUTH_GITHUB_ID="your-github-client-id"
AUTH_GITHUB_SECRET="your-github-client-secret"
# Google OAuth
AUTH_GOOGLE_ID="your-google-client-id"
AUTH_GOOGLE_SECRET="your-google-client-secret"

10. Set up Stripe integration by adding your API keys to the environment file:

STRIPE_SECRET_KEY="sk_test_your-stripe-secret-key"
STRIPE_WEBHOOK_SECRET="whsec_your-webhook-secret"
STRIPE_PORTAL_RETURN_URL="http://localhost:3000/dashboard"

Configure your Stripe webhook endpoint to point to https://your-app-url/api/stripe and select the events you want to handle. The starter kit includes an example handler for the customer.subscription.updated event.

11. Configure Amazon SES for email delivery:

AWS_SES_ACCESS_KEY_ID="your-ses-access-key"
AWS_SES_SECRET_ACCESS_KEY="your-ses-secret-key"
AWS_SES_REGION="us-east-1"

12. Add your tracking IDs for analytics services:

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID="GA4-MEASUREMENT-ID"
NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID="GTM-XXXXXXX"
NEXT_PUBLIC_AUTHORITY="https://yourdomain.com"

13. Start the development server. Your application will be available at http://localhost:3000. The development server includes hot reloading, so changes to your code will automatically refresh the browser.

bun dev

14. The starter kit includes a GitHub Actions workflow for automated deployment. Configure your deployment environment variables in your hosting provider and push your code to trigger the build pipeline.

For Docker deployment, build and run the container:

docker build -t catalyst-app .
docker run -p 3000:3000 catalyst-app

Update your environment variables for production use, particularly the AUTH_SECRET, database connection strings, and API keys.

Related Resources

• Next.js Documentation – Official guide to the React framework used in this starter kit.
• Prisma Documentation – Learn about the ORM and database management features.
• Auth.js Documentation – Authentication library documentation with provider setup guides.
• Stripe Developer Docs – Payment processing integration guides and API references.

FAQs

Q: Can I use a different database instead of PostgreSQL?
A: Yes, Prisma supports multiple database providers, including MySQL, SQLite, and MongoDB. Update your DATABASE_URL in the .env file and modify the provider in your prisma/schema.prisma file accordingly.

Q: How do I customize the authentication providers?
A: Modify the src/auth.ts file to add or remove authentication providers. Auth.js supports over 80 providers, including Discord, Twitter, Apple, and custom email/password authentication.

Q: Is the starter kit suitable for production use?
A: Yes, the starter kit includes production-ready configurations for security, performance, and scalability. However, you should review and customize the settings based on your specific requirements and security policies.

Q: Can I use npm or yarn instead of Bun?
A: Yes, the project includes package.json scripts that work with npm, yarn, and pnpm. Simply use your preferred package manager for installation and running commands.