StackForDevs Starter App

A production-ready React/Next.js application demonstrating StackForDevs integration with authentication, notifications, and secure architecture.

💡 Perfect for: Quick starts, learning StackForDevs APIs, building prototypes, or using as a foundation for your application.

What's Included

🔐 Authentication

Complete login and registration flows with JWT token management

🔔 Notifications

Send, view, and manage in-app notifications with real-time updates

🔒 Secure Architecture

Two-tier design with API proxy server that keeps secrets server-side

✨ Beautiful UI

Tailwind CSS design matching the admin dashboard aesthetic

🐳 Docker Ready

Docker Compose setup for one-command deployment

⚡ Pre-Configured

Download with your credentials already set up in .env file

Download & Setup

Get started in under 5 minutes with the pre-configured starter app:

Step 1: Download the Starter App

  1. Log in to StackForDevs Dashboard
  2. Navigate to the Integration Guide page
  3. Click "Download Starter App with .env (ZIP)"
  4. The ZIP includes your credentials pre-configured!

Step 2: Extract the Archive

unzip stackfordevs-starter-app.zip
cd stackfordevs-starter-app

# Verify you're in the correct directory
ls -la
# You should see: package.json, src/, api/, .env, docker-compose.yml

Step 3: Choose Your Method

You can run the starter app with Docker (recommended) or locally for development.

Docker Setup (Recommended)

The easiest way to get started - runs both frontend and API server with one command:

Quick Start with Docker

# Make the script executable
chmod +x docker-run.sh

# Build and run
./docker-run.sh

# Or use Docker Compose directly
docker compose up -d --build

# View logs
docker compose logs -f

# Stop services
docker compose down
✓ That's it! Open http://localhost:3000 in your browser.

What docker-run.sh Does

  1. Builds Docker images for frontend and API server
  2. Starts both services in containers
  3. Frontend runs on http://localhost:3000
  4. API server runs on http://localhost:3001

Docker Architecture

docker-compose.yml
├── Frontend Container (Next.js)
│   └── Port 3000
└── API Server Container (Express)
    └── Port 3001

Local Development Setup

For development with hot-reload and debugging, run locally:

Prerequisites

Step 1: Start the API Server

Open a terminal and run:

cd api
npm install
npm run dev

# API server starts on http://localhost:3001

Step 2: Start the Frontend

Open a second terminal and run:

# From the root directory
npm install
npm run dev

# Frontend starts on http://localhost:3000

Step 3: Open Your Browser

Navigate to http://localhost:3000 and start building!

Both servers must run: The frontend needs the API server to proxy requests to StackForDevs APIs with your secret key.

Application Architecture

The starter app uses a secure two-tier architecture:

Security Model

Browser (Port 3000)
    ↓ HTTP request
Frontend (Next.js)
    ↓ Calls local API
API Server (Express on Port 3001)
    ↓ Adds secret keys
StackForDevs APIs
    └── auth-service
    └── notification-service

Why Two Tiers?

Project Structure

stackfordevs-starter-app/
├── src/                    # Frontend (Next.js)
│   ├── app/
│   │   ├── page.tsx        # Login page
│   │   ├── register/
│   │   │   └── page.tsx    # Registration
│   │   └── dashboard/
│   │       └── page.tsx    # Dashboard with notifications
│   ├── components/
│   │   ├── LoginForm.tsx
│   │   ├── RegisterForm.tsx
│   │   ├── SendNotification.tsx
│   │   └── NotificationList.tsx
│   ├── context/
│   │   └── AuthContext.tsx # Auth state management
│   └── lib/
│       └── api.ts          # API client
├── api/                    # API Server (Express)
│   └── src/
│       └── index.ts        # Proxy routes
├── .env                    # Your credentials (pre-configured)
├── docker-compose.yml      # Docker setup
├── Dockerfile              # Frontend image
└── package.json            # Frontend dependencies

How Requests Flow

  1. User fills out login form in browser
  2. Frontend calls http://localhost:3001/api/auth/login
  3. API server adds credentials from .env
  4. API server forwards to https://auth.stackfordevs.com/v1/login
  5. Response flows back through API server to frontend
  6. Frontend stores JWT token and updates UI

Customization

The starter app is designed to be extended and customized:

1. Styling

Customize the look and feel with Tailwind CSS:

// tailwind.config.js - Update colors and theme
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#124AFF',  // Change your brand color
        secondary: '#05111A'
      }
    }
  }
}

2. Adding New API Endpoints

Add routes to the API server:

// api/src/index.ts
app.get('/api/custom-endpoint', async (req, res) => {
  const response = await fetch(
    'https://auth.stackfordevs.com/your-endpoint',
    {
      headers: getHeaders()  // Includes secret key
    }
  );
  res.json(await response.json());
});

3. Adding New Pages

Create pages in the Next.js app router:

// src/app/profile/page.tsx
export default function ProfilePage() {
  return (
    <div>
      <h1>User Profile</h1>
      {/* Your profile UI */}
    </div>
  );
}

4. Environment-Specific Configs

Use different .env files for each environment:

# .env.development
NEXT_PUBLIC_PROJECT_ID=project-dev-id

# .env.production
NEXT_PUBLIC_PROJECT_ID=project-prod-id

# Load with:
NODE_ENV=production npm run build

Troubleshooting

Common Issues

Error: "useAuth must be used within AuthProvider"

Cause: Running from wrong directory

Solution:

cd stackfordevs-starter-app
ls -la  # Verify package.json exists
npm run dev

Error: "POST /undefined/login 404"

Cause: Environment variables not loaded

Solution:

# Verify .env file exists
cat .env

# Clear cache and restart
rm -rf .next
npm run dev

No Styling (White Background)

Cause: Tailwind not built

Solution:

npm install
rm -rf .next
npm run dev

Login/Registration Failing

Causes: Invalid credentials or API keys

Solution:

  • Verify API keys in Projects Dashboard
  • Re-download the starter app with fresh credentials
  • Check API server logs: docker compose logs api

Debugging Tips

# View Docker logs
docker compose logs -f frontend
docker compose logs -f api

# Check environment variables loaded
# Open browser console, you should see:
# "✅ All environment variables loaded successfully"

# Test API server directly
curl http://localhost:3001/health

Deployment

Docker Deployment

Deploy to any server with Docker:

# Build for production
docker compose -f docker-compose.yml build

# Run in production mode
docker compose up -d

# View status
docker compose ps

Vercel Deployment

  1. Push code to GitHub
  2. Import repository in Vercel
  3. Add environment variables from .env
  4. Deploy!
Production Note: Deploy the API server separately (e.g., on Heroku, Railway, or AWS) and update NEXT_PUBLIC_API_URL to point to it.

Next Steps

🔐 Authentication

Deep dive into auth implementation

🔔 Notifications

Learn notification patterns