Astra - AI Web Code Editor

Next.js app with Clerk authentication and Convex as the backend. It also includes an Inngest endpoint and optional integrations for Google/Anthropic (AI SDK), Firecrawl, and Sentry.

Prerequisites

• Node.js: 20+ recommended
• npm: this repo includes a package-lock.json (use npm ci)
• Accounts/API keys (depending on what you use):
  • Convex (required)
  • Clerk (required)
  • Google Generative AI (required for /api/suggestion and the Inngest demo)
  • Firecrawl (optional, only needed if you run URL scraping in the Inngest demo)
  • Sentry (optional, only needed for source map upload in CI/builds)

Setup

Install dependencies:

npm ci

Create your env file:

cp .env.example .env.local

Then fill in .env.local.

Environment variables

These are the env vars used by this repo:

• Required (app won’t run)

  • NEXT_PUBLIC_CONVEX_URL: Convex HTTP URL (the app throws on startup if missing)
  • CONVEX_DEPLOYMENT: Convex deployment identifier (used by the Convex CLI)
  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: Clerk publishable key
  • CLERK_SECRET_KEY: Clerk secret key
  • CLERK_JWT_ISSUER_DOMAIN: Clerk JWT issuer domain used by Convex auth config (convex/auth.config.ts)

• Required for AI features

  • GOOGLE_GENERATIVE_AI_API_KEY: required for /api/suggestion and the Inngest demo (uses google("gemini-2.5-flash"))
  • ANTHROPIC_API_KEY: optional unless you wire features to Anthropic

• Optional

  • FIRECRAWL_API_KEY: only needed if you use the Inngest demo’s URL scraping
  • SENTRY_AUTH_TOKEN: only needed for uploading sourcemaps (build/CI); runtime DSN is configured in sentry.*.config.ts

Running locally

This project uses Convex, so you typically run two dev processes:

Terminal A (Convex):

npx convex dev

Terminal B (Next.js):

npm run dev

Then open http://localhost:3000.

Inngest (optional)

The Inngest handler is exposed at /api/inngest. If you want to run Inngest locally, start the dev server and point it at your local endpoint:

npx inngest-cli@latest dev -u http://localhost:3000/api/inngest

Scripts

npm run dev     # start Next.js dev server
npm run build   # production build
npm run start   # run production server
npm run lint    # eslint

Troubleshooting

• Missing NEXT_PUBLIC_CONVEX_URL: the app throws at startup. Make sure .env.local exists and contains a valid Convex URL.
• Clerk + Convex auth issues: confirm CLERK_JWT_ISSUER_DOMAIN matches your Clerk instance domain and that Clerk keys are set correctly.
• AI requests failing: ensure GOOGLE_GENERATIVE_AI_API_KEY is set; the AI SDK provider will error if the key is missing/invalid.