Skip to content
GitHubLinkedIn
Live demo

Local Setup

This guide walks you through setting up SparkFeed on your local machine from scratch.

  1. Clone the repository

    git clone https://github.com/Sparkable-dev/SparkFeed.git sparkfeed
    cd sparkfeed

  2. Install dependencies

    SparkFeed uses Bun as its package manager and runtime. Install it first if you haven’t:

    curl -fsSL https://bun.sh/install | bash

    Then install project dependencies:

    bun install

  3. Set up environment variables

    Copy the example environment file:

    cp .env.example .env.local

    At minimum, set BETTER_AUTH_SECRET, a long random string used to sign sessions:

    openssl rand -base64 32   # paste the output as BETTER_AUTH_SECRET
    # .env.local
    BETTER_AUTH_SECRET=your-generated-secret-here

    The database defaults to file:rss.db locally, so no DATABASE_URL is needed for development. See Environment Variables for the full reference.

  4. Initialize the database

    Push the Drizzle schema to your local SQLite database:

    bun run db:push

    This creates rss.db in the project root with all required tables.

  5. Start the dev server

    bun run dev

    Open http://localhost:3000. You’ll be prompted to create an account on first visit.

Project structure

Section titled “Project structure”
sparkfeed/                  ← the app (TanStack Start)
├── src/
│   ├── components/         ← UI components
│   ├── config/             ← JSON configs (AI models, demo feeds)
│   ├── db/                 ← Drizzle schema + client
│   ├── hooks/              ← React hooks
│   ├── lib/                ← Auth client, email, demo constants
│   ├── routes/             ← TanStack Router file-based routes
│   └── server/             ← Server functions (RSS, AI, email actions)
├── drizzle/                ← Migration SQL files
├── drizzle.config.ts
├── rss.db                  ← Local dev database (gitignored)
├── .env.local              ← Your local secrets (gitignored)
└── package.json

Optional: enable AI and email

Section titled “Optional: enable AI and email”

SparkFeed works without AI or email keys. Those features are simply inactive. Add keys when you’re ready:

# .env.local: add any of these to unlock features
OPENAI_API_KEY=sk-...        # enables Spark AI
RESEND_API_KEY=re_...        # enables email verification + password reset
EMAIL_FROM=SparkFeed <[email protected]>

See AI Providers and Environment Variables for the full setup.

Next step

Section titled “Next step”

Ready to start the app? Go to Run the Project →