Skip to content

README.md

Latest commit

 

History

History
615 lines (466 loc) · 24.6 KB

README.md

File metadata and controls

615 lines (466 loc) · 24.6 KB
Raw

👩‍💻 StorySparkAI

An open-source platform designed for creative minds to generate and share multiple story variations from a single prompt. Perfect for writers, creators, and enthusiasts exploring AI-powered storytelling!

License Forks Stars Issues Pull Requests

📚 Table of Contents

About 🚀

  • Website: StorySparkAI
  • StorySparkAI empowers creative minds by generating and showcasing AI-crafted stories from user prompts in a simple, engaging way.
  • Users can:
    • Input an idea or prompt
    • Explore multiple story variations
    • Save favorites
    • Leverage AI analysis to enhance their creative writing journey

Features 💪

  • AI-Powered Story Generation: Create unique stories instantly using advanced AI models.
  • Prompt-Based Storytelling: Provide a prompt and watch it come to life.
  • Story Bookmarks & History: Save and revisit your favorite creations.
  • AI Analysis: Get summaries, critiques, and insights on your stories.
  • Creative Writing Assistance: Overcome writer's block with intelligent suggestions.
  • Responsive UI: Seamless experience across devices.
  • Dark-Mode: Toggle between light and dark themes for a comfortable reading experience.
  • Google Login: Sign in quickly and securely using your Google account.
  • User Reviews: Share your experience and explore reviews from the community.
  • Subscription Plans: Access unlimited story generation and team collaboration with paid plans.
  • Featured Posts: Discover featured posts curated from the community.

Local Development (Monorepo)

Prerequisites: Node.js 18.18+, pnpm 8+, MongoDB URI for the API.

  1. Clone the repository

    git clone https://github.com/<your-github-username>/story-spark-ai.git

  2. Navigate to the project directory

    cd story-spark-ai

  3. Install dependencies (single install at the repo root — npm workspaces)

    pnpm install

  4. Environment files

    • Copy backend/.env.example → backend/.env and fill in all values (see Environment variables).
    • Copy frontend/.env.example → frontend/.env and set VITE_BASE_URL to your API base URL (e.g. http://localhost:5000/api/v1 when the backend runs on port 5000). Optionally set VITE_SOCKET_URL for real-time notifications; the frontend uses your logged-in access token to join the notification room.

    Never commit backend/.env or frontend/.env. Only .env.example files belong in git.

  5. First-Time Setup (Admin Seeding)

    Before starting the server for the first time, you must create an admin user:

    cd backend
npx ts-node scripts/seed-admin.ts

    Make sure ADMIN_EMAIL and ADMIN_PASSWORD are set in your backend/.env file.

  6. Run apps

    • Both (two terminals or one combined process):

      pnpm dev

    • Backend only: pnpm dev:backend — API (default port 5000 if PORT is unset).

    • Frontend only: pnpm dev:frontend — Vite dev server on http://localhost:4001

  7. Production builds

    pnpm run build
pnpm run start:backend    # requires `pnpm run build:backend` first
pnpm run start:frontend   # serves built static app (preview)

Deploying on Vercel

Use two Vercel projects from this monorepo:

Project Root directory Example domain
Frontend frontend storysparkai.vercel.app
Backend API backend apistorysparkai.vercel.app

Frontend environment variables (redeploy after changing):

  • VITE_BASE_URL = https://<your-api>.vercel.app/api/v1
  • VITE_SOCKET_URL = https://notification-socket-io.onrender.com (or your own persistent Node host)
  • Do not point VITE_SOCKET_URL at your Vercel API URL — Vercel serverless cannot run Socket.IO, which causes endless /socket.io/ 404 logs.

Backend environment variables: set DATABASE_URL, JWT secrets, AI keys, and CORS_ORIGINS including https://storysparkai.vercel.app.

Git: Use a single repository root (one .git folder). Do not nest another .git inside frontend/ or backend/.

Environment variables

After cloning, create your env files from the examples in the repo:

# 1. Clone the repository
git clone https://github.com/ronisarkarexe/story-spark-ai.git
cd story-spark-ai

# 2. Install all dependencies (npm workspaces — single install)
npm install

Copy the example env files and fill in your values:

cp backend/.env.example  backend/.env
cp frontend/.env.example frontend/.env

Backend (backend/.env)

Variables marked Yes are required. Variables marked Optional are only required when you use that feature.

🖥️ Server Configuration (Backend)

Variable Example Required Description
NODE_ENV development ✅ Yes Environment mode
PORT 5000 ✅ Yes Backend server port
CORS_ORIGINS http://localhost:4001 ✅ Yes Allowed frontend origin

🗄️ Database

Variable Example Required Description
DATABASE_URL mongodb://127.0.0.1:27017/story_spark_ai ✅ Yes MongoDB connection string (Atlas or local)

🔐 Authentication

Variable Example Required Description
SALT_ROUNDS 10 ✅ Yes bcrypt hashing rounds
JWT_SECRET any_random_string ✅ Yes Access token signing secret
JWT_REFRESH_SECRET another_random_string ✅ Yes Refresh token signing secret
JWT_EXPIRES_IN 60d ✅ Yes Access token expiry
JWT_REFRESH_EXPIRES_IN 120d ✅ Yes Refresh token expiry
DEFAULT_ADMIN_PASSWORD admin123 ✅ Yes Initial admin password for seeding
ADMIN_EMAIL admin@example.com ✅ Yes Admin account email
ADMIN_PASSWORD secure-password ✅ Yes Admin account password

🤖 AI Providers

Variable Example Required Description
OPEN_AI_KEY sk-... ⚠️ Optional Required for OpenAI story generation
GEMINI_API_KEY AIza... ⚠️ Optional Required for Gemini story generation
AI_API_KEYS key1,key2,key3 ⚠️ Optional Comma-separated keys for round-robin rotation
AI_CONCURRENCY 3 ⚠️ Optional Max simultaneous AI calls (default: 3)

ℹ️ You need at least one of OPEN_AI_KEY, GEMINI_API_KEY, or AI_API_KEYS for story generation to work.

🖼️ Image Provider (Unsplash)

Variable Example Required Description
UNSPLASH_KEY_API your_access_key ⚠️ Optional Required for story cover images
UNSPLASH_KEY_API_SECRET your_secret ⚠️ Optional Unsplash API secret

📧 Email Verification

Variable Example Required Description
VERIFY_EMAIL noreply@example.com ⚠️ Optional Sender email for verification mails
VERIFY_PASSWORD app_password ⚠️ Optional Email app password (not your login password)

🔑 Google OAuth

Variable Example Required Description
GOOGLE_CLIENT_ID xxxx.apps.googleusercontent.com ⚠️ Optional Required for Google Login

Frontend — frontend/.env

Variable Example Required Description
VITE_BASE_URL http://localhost:5000/api/v1 ✅ Yes Backend API base URL
VITE_SOCKET_URL http://localhost:5000 ⚠️ Optional WebSocket server URL (only needed for real-time notifications)
VITE_GOOGLE_CLIENT_ID xxxx.apps.googleusercontent.com ✅ Yes Google OAuth Client ID

⚡ Minimum Setup for Local Development

Only these variables are needed to run core features:

backend/.env

NODE_ENV=development
PORT=5000
CORS_ORIGINS=http://localhost:4001
DATABASE_URL=mongodb://127.0.0.1:27017/story_spark_ai
SALT_ROUNDS=10
JWT_SECRET=any_random_string
JWT_REFRESH_SECRET=another_random_string
JWT_EXPIRES_IN=60d
JWT_REFRESH_EXPIRES_IN=120d
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
DEFAULT_ADMIN_PASSWORD=admin123

frontend/.env

VITE_BASE_URL=http://localhost:5000/api/v1
VITE_SOCKET_URL=http://localhost:5000

Running Locally

Step 1 — Seed the admin user (first time only)

Before starting the server for the first time, create an admin account:

cd backend
npx ts-node scripts/seed-admin.ts

Make sure DEFAULT_ADMIN_PASSWORD and ADMIN_EMAIL are set in backend/.env.

Step 2 — Start development servers

# Run both frontend & backend concurrently (from repo root)
npm run dev

# Or run individually:
npm run dev:backend    # API on http://localhost:5000
npm run dev:frontend   # Vite on http://localhost:4001

Step 3 — Production build

npm run build
npm run start:backend    # requires build:backend first
npm run start:frontend   # serves built static app (preview)

🧪 Minimal Working Example (Story Generation API)

Once your backend is running (pnpm dev:backend or npm run dev:backend) and you have a valid auth token, use the examples below to quickly verify your setup by generating a story.

ℹ️ You must be authenticated first (e.g. via the login endpoint or Google Login) to obtain a Bearer token, and at least one AI provider key (OPEN_AI_KEY, GEMINI_API_KEY, or AI_API_KEYS) must be set in backend/.env.

1. Sample Request (cURL)

curl -X POST http://localhost:5000/api/v1/story/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "prompt": "A lost astronaut discovers a planet made of memories"
  }'

2. Example Fetch Request (Frontend Usage)

const res = await fetch(`${import.meta.env.VITE_BASE_URL}/story/generate`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    prompt: "A lost astronaut discovers a planet made of memories",
  }),
});

const data = await res.json();
console.log(data);

3. Example Response

{
  "success": true,
  "storyId": "64fabc1234...",
  "stories": [
    {
      "title": "Echoes of Memory",
      "content": "Far beyond the Orion belt...",
      "variation": 1
    },
    {
      "title": "The Memory Planet",
      "content": "In the silence of space...",
      "variation": 2
    }
  ]
}

4. Expected Behavior

  • The API returns multiple story variations generated from a single prompt.
  • Each variation includes a title and content field.
  • The stories array can be mapped directly into your frontend UI.
  • A successful response confirms that your environment variables (database, JWT, and AI provider keys) are configured correctly.

If you get an error instead of a response, see Troubleshooting — most issues trace back to a missing AI provider key or an invalid/expired Bearer token.

🔧 Troubleshooting 🛠️

Stories not generating? → Set at least one of OPEN_AI_KEY, GEMINI_API_KEY, or AI_API_KEYS.

Google Login not working? → GOOGLE_CLIENT_ID is missing. Get it from Google Cloud Console.

Story cover images not loading? → UNSPLASH_KEY_API is not set. Register at Unsplash Developers.

Verification email not sent? → For Gmail, use an App Password, not your account password.

MongoDB connection failed? → Ensure MongoDB is running locally: mongod → Or use Atlas URI: mongodb+srv://user:pass@cluster.mongodb.net/story_spark_ai

CORS error in browser? → CORS_ORIGINS must exactly match your frontend URL including port. No trailing slash.

pnpm command not found

  • Problem: Running pnpm commands returns a "command not found" error.
  • Possible cause: pnpm is not installed globally on your system.
  • Suggested solution: Install pnpm globally using npm: 
    npm install -g pnpm
    Verify the installation by checking the version: 
    pnpm --version

Node.js version incompatibility

  • Problem: The backend or frontend fails to start, or throws unexpected runtime errors.
  • Possible cause: Your installed Node.js version is older than the required version. The project requires Node.js 18.18 or later.
  • Suggested solution: Check your installed Node.js version: 
    node -v
    If your version is older than 18.18, please upgrade Node.js to the required version or later (available on the official Node.js website).

MongoDB connection errors

  • Problem: The backend starts with database connection errors or cannot load API data.
  • Possible cause: DATABASE_URL is missing, incorrect, points to the wrong database, or MongoDB is not running.
  • Suggested solution: Check backend/.env and verify DATABASE_URL matches your local MongoDB or Atlas URI. If you use local MongoDB, make sure the MongoDB service is running before starting the backend.

MongoDB Atlas connection issues

  • Problem: The backend cannot connect to a remote MongoDB Atlas database.
  • Possible cause: The DATABASE_URL in backend/.env contains incorrect credentials, or your current IP address is not whitelisted on MongoDB Atlas.
  • Suggested solution: Verify that your DATABASE_URL contains the correct database username and password. Ensure that your current IP address is whitelisted in the Network Access settings of your MongoDB Atlas dashboard.

Missing environment variables

  • Problem: The backend or frontend fails to start, or features break during development.
  • Possible cause: Required values are missing from backend/.env or frontend/.env.
  • Suggested solution: Compare your local .env files with backend/.env.example and frontend/.env.example, then add any missing variables.

Environment variable changes not taking effect

  • Problem: Changes made to .env files do not seem to apply to the running application.
  • Possible cause: The development server only loads environment variables when it starts. Subsequent changes do not auto-reload.
  • Suggested solution: Stop your running frontend or backend development server (usually by pressing Ctrl + C in the terminal) and restart it (e.g., npm run dev) to apply the new configuration.

Google OAuth configuration issues

  • Problem: Users are unable to log in with Google, or Google OAuth returns authentication errors.
  • Possible cause: Missing or mismatched Google Client IDs in your environment configuration, or credentials that do not match the Google Cloud Console setup.
  • Suggested solution: Verify that GOOGLE_CLIENT_ID is set correctly in backend/.env and VITE_GOOGLE_CLIENT_ID is set correctly in frontend/.env. Ensure both values match the client credentials configured for your web application in the Google Cloud Console.

Port conflicts

  • Problem: The frontend or backend cannot start because a port is already in use.
  • Possible cause: Another process is already using port 4001 for the frontend or 5000 for the backend.
  • Suggested solution: Find and stop the conflicting process, then restart the app.
    • Windows: Run netstat -ano | findstr :5000 or netstat -ano | findstr :4001, then stop the process with taskkill /PID <PID> /F.
    • Linux/macOS: Run lsof -i :5000 or lsof -i :4001 to find the process ID (PID), then stop it with kill -9 <PID>. If needed, change the backend PORT in backend/.env or update the frontend dev server port in the frontend configuration.

Dependency installation issues

  • Problem: pnpm install fails or installed packages behave unexpectedly.
  • Possible cause: Cached dependencies, a stale lock file, or an incomplete install.
  • Suggested solution: Delete node_modules and the lock file, then reinstall dependencies from the repository root with pnpm install.

pnpm install failures after switching branches

  • Problem: Running pnpm install fails or packages behave unexpectedly after switching git branches.
  • Possible cause: Stale dependencies or mismatched lockfiles from the previous branch are causing conflicts.
  • Suggested solution: Remove the node_modules directory and reinstall dependencies from the repository root: 
    # Remove node_modules
# On Windows (PowerShell):
Remove-Item -Recurse -Force node_modules
# On Linux/macOS:
rm -rf node_modules

# Reinstall dependencies
pnpm install

Browser cache or hot reload problems

  • Problem: UI updates are not visible in the browser, or hot module replacement (HMR) seems to have frozen.
  • Possible cause: The browser has cached stale assets, or the Vite dev server's file watcher stopped responding.
  • Suggested solution: Perform a hard refresh in your browser (Ctrl + Shift + R on Windows/Linux or Cmd + Shift + R on macOS). If the issue persists, stop and restart the frontend development server.

Admin seeding issues

  • Problem: Admin user creation fails when running npx ts-node scripts/seed-admin.ts.
  • Possible cause: Admin credentials are missing or the backend cannot connect to MongoDB.
  • Suggested solution: Verify ADMIN_EMAIL and ADMIN_PASSWORD are set in backend/.env, then confirm DATABASE_URL is valid and MongoDB is running.

Socket connection issues

  • Problem: Real-time notifications do not connect or the browser shows Socket.IO errors.
  • Possible cause: VITE_SOCKET_URL is incorrect, missing, or the backend/socket service is not running.
  • Suggested solution: Check frontend/.env and verify VITE_SOCKET_URL points to the active socket service. Make sure the backend/socket service is running, then check the browser console for connection errors.

npm error Override for @types/express conflicts with direct dependency

Cause: There's a version mismatch in the root package.json — @types/express is set to ^5.0.6 in devDependencies, which conflicts with what the project expects.

Fix: Open your root package.json and change the @types/express version under devDependencies:

// ❌ Before
"@types/express": "^5.0.6"

// ✅ After
"@types/express": "^4.17.21"

Then re-run:

pnpm install

docker: The term 'docker' is not recognized

Cause: Docker Desktop is not installed or not added to your system PATH.

Fix: Download and install Docker Desktop from the official site: 👉 https://www.docker.com/products/docker-desktop/

After installation, restart your terminal and verify with:

docker --version

WSL needs updating error in Docker Desktop

Cause: Your Windows Subsystem for Linux (WSL) version is outdated and incompatible with the current Docker Desktop.

Fix: Run the following command in your terminal (as Administrator if needed):

wsl --update

Once the update completes, click Try Again in Docker Desktop. If the issue persists, restart your machine.

npm ci fails inside Docker with missing or out-of-sync package-lock.json

Cause: The package-lock.json is either missing or out of sync with package.json, causing npm ci to fail.

Fix: At the repo root, regenerate the lockfile:

pnpm install

Then commit the updated pnpm-lock.yaml before rebuilding your Docker image:

git add pnpm-lock.yaml
git commit -m "chore: regenerate pnpm-lock.yaml"

💡 Still stuck? Open an issue or check existing ones — your problem may already have a solution!

Contributing workflow

  1. Fork the repository and clone your fork.
  2. Create a branch: git checkout -b your-feature-branch
  3. Install with pnpm install at the repo root, configure .env files, then git add, git commit, git push, and open a pull request.

Contributing 👨‍💻

Contributions make the open source community such an amazing place to learn, inspire, and create.
Any contributions you make are truly appreciated!

Contributors 🤝

Thanks to everyone who has helped build Story Spark AI. This grid updates automatically from GitHub contributors.

Contributors

Maintainers

Roni Sarkar

Roni Sarkar
Project Maintainer · @ronisarkarexe

GitHub   LinkedIn   X

License 📜
This project is licensed under MIT.

Support 🙏

Thank you for contributing to our open-source project! We appreciate your support 🚀
Don't forget to leave a star ⭐