Project Structure

A Superfunction project organizes your Next.js app, backend server, and shared types in a single codebase.

Directory Structure

Terminal
my-app/
├─ src/
│  ├─ app/                  # Next.js App Router
│  │  ├─ page.tsx
│  │  └─ layout.tsx
│  │
│  ├─ server/               # Superfunction Backend
│  │  ├─ routes/            # Route definitions
│  │  │  ├─ users.ts        # User routes (getUser, createUser, ...)
│  │  │  ├─ examples.ts     # Example routes
│  │  │  └─ health.ts       # Health check route
│  │  ├─ entities/          # Database schemas (Drizzle)
│  │  │  └─ users.ts
│  │  ├─ repositories/      # Repository pattern
│  │  │  └─ user.repository.ts
│  │  ├─ router.ts          # Main router (defineRouter)
│  │  └─ drizzle/           # Generated migrations
│  │
│  └─ lib/                  # Shared code
│     └─ api-client.ts      # Auto-generated client
│
├─ .env                     # Environment variables
├─ docker-compose.yml       # Database services
├─ next.config.ts           # Next.js config
├─ .spfnrc.json             # Superfunction config
└─ package.json

Key Directories

src/app/

Your Next.js application using the App Router. This is where your frontend code lives—pages, layouts, components, and client-side logic.

src/server/

Your backend server implementation:

• routes/ - Route definitions using define-route system
• entities/ - Drizzle ORM database schemas
• repositories/ - Repository classes for data access
• router.ts - Main router combining all routes
• drizzle/ - Generated migration files

src/lib/

Shared code used by both backend and frontend:

• api-client.ts - Auto-generated type-safe client

src/components/

React components for your Next.js application.

Configuration Files

.spfnrc.json

Superfunction configuration for code generation:

json
{
    "codegen": {
        "generators": [
            {
                "name": "@spfn/core:router",
                "enabled": true
            }
        ]
    }
}

spfn.config.js

Deployment configuration for SuperCloud (Superfunction cloud platform):

javascript
export default {
    packageManager: 'pnpm',

    deployment: {
        subdomain: 'my-app',     // yourapp.us.spfn.app
        region: 'us',            // Deployment region

        customDomains: {
            nextjs: ['www.example.com'],  // Custom frontend domain
            spfn: ['api.example.com']     // Custom API domain
        },

        env: {
            // Auto-generated by default, override if needed
            // NEXT_PUBLIC_API_URL: automatically set
            // API_URL: automatically set
        }
    }
}

Note: SuperCloud (Coming Soon): Deploy with git push to Superfunction's managed infrastructure.

drizzle.config.ts

Drizzle ORM configuration for database migrations and type generation.

---

Ready to build?

Learn how to create your first backend API with Superfunction.

Create Your First API →