Installation & Setup - Etown-CS310/Story-Forge GitHub Wiki

This guide will help you get StoryForge running on your local machine.

Prerequisites

Make sure you have the following installed:

  • Node.js (v18 or higher recommended)
  • npm (comes with Node.js)

You will also need accounts for:

  • Convex (for backend and database)
  • WorkOS (for authentication)
  • OpenAI (for AI assistant features)

Optional but recommended:

Step 1: Clone the Repository

Open your terminal and clone the project:

git clone https://github.com/<your-username>/<repo-name>.git

Navigate into the project folder:

cd StoryForge

Step 2: Install Dependencies

Install all required packages with npm:

npm install

This will install all frontend and backend dependencies necessary for development.

Step 3: Set Up Convex Backend

Initialize your Convex backend:

npx convex dev

This will:

  • Create a new Convex deployment (if this is your first time)
  • Generate your CONVEX_DEPLOYMENT ID
  • Provide your VITE_CONVEX_URL
  • Sync your database schema

Keep this terminal running - it watches for changes to your Convex functions.

Step 4: Configure Environment Variables

In a new terminal window, copy the example environment file:

cp .env.local.example .env.local

Open .env.local in your code editor and fill in your actual values:

  • CONVEX_DEPLOYMENT: Copy from the npx convex dev output above
  • VITE_CONVEX_URL: Copy from the npx convex dev output above
  • VITE_WORKOS_CLIENT_ID: Get from your WorkOS Dashboard
  • VITE_WORKOS_REDIRECT_URI: Use http://localhost:5173/callback for local development

Step 5: Add Your OpenAI API Key to Convex

StoryForge’s AI Assistant requires access to OpenAI’s API. Get your API key from the OpenAI Dashboard.

Store it securely in Convex’s environment storage by running:

npx convex env set OPENAI_API_KEY sk-your-openai-key-here

Verify it’s set:

npx convex env list

You should see:

OPENAI_API_KEY=sk-************************

Your key is stored securely on Convex’s backend — it will not be exposed in .env.local or client code.

Step 6: Run the Development Server

In the same terminal (or a new one), start the local development server:

npm run dev

By default, the app should be accessible at http://localhost:5173 in your browser.

Troubleshooting

  • Convex errors: Make sure npx convex dev is still running in a separate terminal
  • Authentication issues: Verify your WorkOS credentials are correct in .env.local
  • Port conflicts: If port 5173 is in use, Vite will automatically try the next available port
⚠️ **GitHub.com Fallback** ⚠️