A Next.js (App Router) application for screening US equities and options with live market data, modern UI (shadcn/ui + Tailwind), and both Novice and Advanced dashboards.

• Live stocks data (prices, volume, OHLC) via Polygon.io
• Indices (S&P 500, Dow 30, Nasdaq, VIX) via FMP (Financial Modeling Prep)
• One-Click Screeners (Trending, Value, Growth, Volume) with volume and market cap
• Quick Search with enriched market cap
• Optional features: Portfolio overview, Active screeners, Live alerts

• Framework: Next.js 14 (App Router, SSR)
• Language: TypeScript / React 18
• UI: TailwindCSS, shadcn/ui
• Data:
  • Polygon.io (Stocks: snapshots, aggregates, indicators)
  • FMP (Indices: ^GSPC, ^DJI, ^IXIC, ^VIX)
• Auth: NextAuth (configured, optional)
• DB: Prisma + (optional) Postgres (e.g., Supabase) — not strictly required to run core features

Create a .env.local (for local) or set these in your deployment environment:

Required

• NEXTAUTH_SECRET — random string (required if NextAuth used)
• POLYGON_API_KEY — Polygon API key
• FMP_API_KEY — Financial Modeling Prep API key

Optional / As needed

• DATABASE_URL — Postgres connection string (Prisma). Only required if you use the DB-backed features.

Recommended (Prod)

• NEXTAUTH_URL — your site base URL in production (e.g., https://your-domain.com)

Note:

• We recommend NOT committing real .env to source control. Instead, commit a .env.example with placeholders, keep .env ignored, and manage secrets in your platform (Vercel/Render) env settings.

Prerequisites

• Node.js 18+
• Yarn v1 (classic) or npm
• Polygon.io API key
• FMP API key

Setup

# Install dependencies yarn # Create local env file cp .env .env.local # or create .env.local manually # Fill POLYGON_API_KEY, FMP_API_KEY, NEXTAUTH_SECRET (and DATABASE_URL if needed)

Run

yarn dev # open http://localhost:3000

Build & start

yarn build yarn start

Scripts

• yarn dev — start dev
• yarn build — production build
• yarn start — run production server
• yarn lint — (optional) lint

• Stocks (prices/volume/aggregates): Polygon.io
• Indices (S&P 500, Dow 30, Nasdaq, VIX): FMP (due to Polygon plan limitations for indices)
• Screeners & Quick Search: Use Polygon for stocks; market cap enriched via Polygon /v3/reference/tickers/{ticker}, with fallback computed as weighted_shares_outstanding * price when market_cap is unavailable.

Make sure both POLYGON_API_KEY and FMP_API_KEY are present.

Vercel auto-detects Next.js and optimizes SSR.

1. Fork or connect the repo to Vercel

• Import GitHub repository in Vercel dashboard

2. Configure Environment Variables (Project Settings → Environment Variables)

• NEXTAUTH_SECRET (required if using NextAuth)
• NEXTAUTH_URL (e.g., https://your-vercel-domain.vercel.app) — set for Production
• POLYGON_API_KEY
• FMP_API_KEY
• DATABASE_URL (only if using DB features)
• Optional: Create separate variables per environment (Development, Preview, Production)

3. Build & Output

• No changes required; Vercel detects Next.js.
• (Advanced) If needed, set Node.js version and region.

4. Deploy

• Trigger a deployment by pushing to the default branch (master).

5. Post-deploy Checks

• Visit /dashboard
• Confirm Market Overview tiles show S&P 500, Dow 30, Nasdaq, VIX values (FMP)
• Run Quick Search (e.g., AAPL) and verify Market Cap & Volume render
• Verify Screeners return populated Volume and Market Cap

Vercel CLI (optional)

npm i -g vercel vercel login vercel link vercel env pull .env.local vercel # deploy preview vercel --prod # deploy production

Render runs the Next.js server as a Node process (SSR).

1. Create a New Web Service

• From Dashboard, “New +” → “Web Service”
• Connect your GitHub repo
• Select branch: master

2. Configure

• Environment: Node
• Build Command: yarn install && yarn build
• Start Command: yarn start
• Node Version: ensure 18+ (use Render’s default or specify in Environment tabs if needed)
• Auto-Deploy: Enable if desired

3. Environment Variables (Settings → Environment)

• Add:
  • NEXTAUTH_SECRET
  • NEXTAUTH_URL (e.g., https://your-render-service.onrender.com)
  • POLYGON_API_KEY
  • FMP_API_KEY
  • DATABASE_URL (optional)
• Save and redeploy

4. Health Check

• Path: /
• Render should detect Next.js server and show healthy after build

5. Post-deploy Checks

• As above (indices tiles, Quick Search Market Cap, Screeners)

Notes:

• Render uses a persistent server process. Ensure the Start Command matches yarn start.
• If using “free” instance types, expect cold starts.

Missing Market Cap in results

• Verify POLYGON_API_KEY is set and valid
• The API call /v3/reference/tickers/{ticker} must be permitted for your Polygon plan
• Fallback computation uses weighted_shares_outstanding * price when Polygon omits market_cap

VIX or Index tiles empty

• Indices use FMP ^VIX, ^GSPC, ^DJI, ^IXIC
• Verify FMP_API_KEY is set and valid
• Check provider status/rate limits

NEXTAUTH warning in dev

• Set NEXTAUTH_URL=http://localhost:3000 (dev) and your production URL (prod)
• Ensure NEXTAUTH_SECRET is a random strong string

.env in Source Control shows as modified

• Keep .env ignored and use platform env variables
• To hide local changes from Git (without committing): git update-index --skip-worktree .env
• Or stop tracking .env entirely and commit .env.example with placeholders

Build failures on Render/Vercel

• Ensure Node 18+ and correct build/start commands
• Remove stale build artifacts: delete .next locally, rebuild, re-push

app/ api/ indices/[symbol]/route.ts # FMP indices endpoint (I:GSPC, I:DJI, I:IXIC, I:VIX) screeners/route.ts # Screeners via Polygon market snapshot + market cap enrichment market-status/route.ts # Market status via Polygon stocks/[symbol]/route.ts # Stocks snapshot + aggregates; quick search enrichment components/ novice-dashboard.tsx # Market Overview (tiles), Quick Search, One-Click Screeners advanced-dashboard.tsx # Pro UI, ChartWidget, Portfolio, Alerts, etc. stock-table.tsx # Results table (volume + formatted market cap) lib/ polygon.ts # Polygon client (snapshots, aggregates, reference overview) fmp.ts # FMP client (indices quotes) 

• Do not commit secrets (.env) to the repository
• Rotate exposed keys if .env was ever committed previously
• Use Vercel/Render environment variable management for production

Proprietary. All rights reserved.