# Project Scaffolding

> Use when starting a new SaaS app or adding structure to one — sets up a Next.js (App Router) + TypeScript project with a sane folder layout, path aliases, server/client boundaries, and the conventions the rest of the stack builds on.

- **Type:** Skill
- **Install:** `agentstack add skill-param087-saas-starter-skills-project-scaffolding`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [param087](https://agentstack.voostack.com/s/param087)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [param087](https://github.com/param087)
- **Source:** https://github.com/param087/saas-starter-skills/tree/main/skills/project-scaffolding

## Install

```sh
agentstack add skill-param087-saas-starter-skills-project-scaffolding
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Project Scaffolding

## Overview

A SaaS codebase lives or dies by its **boundaries**. Pick **Next.js App Router + TypeScript** and commit to one rule: business logic lives in server-only modules, the UI imports from a typed data-access layer, and secrets never cross into client components. Get the skeleton right and every later skill (auth, billing, jobs) slots in cleanly.

## When to use

- Bootstrapping a new SaaS app from zero.
- An existing app has logic scattered across components and route handlers.
- You need a layout that supports multi-tenancy, billing, and background jobs later.

## Folder layout

```
src/
  app/                      # routes (App Router)
    (marketing)/            # public pages
    (app)/                  # authenticated app, wrapped in a layout that checks session
      [org]/                # tenant-scoped routes (see multi-tenancy)
    api/                    # route handlers (webhooks, integrations)
  server/                   # SERVER-ONLY. never imported by client components
    db/                     # schema + drizzle client (database-schema)
    services/               # business logic, one file per domain
    auth/                   # session helpers (authentication)
  lib/                      # isomorphic helpers (pure, no secrets)
  components/               # UI (ui/* are shadcn primitives)
  env.ts                    # typed env (environment-and-config)
```

## Conventions that pay off

- **`import "server-only"`** at the top of every file in `server/` — turns a leaked import into a build error.
- **Path alias `@/*` → `src/*`** in `tsconfig.json` so imports don't rot.
- **Server Actions for mutations, route handlers for webhooks/integrations.** Don't build a REST layer you don't need.
- **One service per domain** (`server/services/billing.ts`), called by actions and route handlers alike — never duplicate logic in the UI.
- **`strict: true`** plus `"noUncheckedIndexedAccess": true` in tsconfig from day one; retrofitting strictness is misery.

## Recommended baseline

```bash
npx create-next-app@latest --ts --app --tailwind --eslint
# then add: drizzle-orm + drizzle-kit, your auth lib, stripe, zod
```

Keep `next.config` minimal; add `experimental.serverActions` only if your version needs it.

## Pitfalls

- **Putting DB calls in client components** — they can't run there and you'll leak the connection string. Use the data-access layer + server components/actions.
- **A `utils.ts` dumping ground** — split `lib/` (pure) from `server/` (privileged).
- **Deferring `strict` mode** — every week without it adds `any` you'll never remove.
- **Route handlers for everything** — Server Actions are less boilerplate for first-party mutations.
- **No route groups** — mixing marketing and app routes makes auth layouts awkward.

## Hand-off

A typed skeleton with clear server/client boundaries. Next: `environment-and-config` for typed secrets, then `database-schema` to model data.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [param087](https://github.com/param087)
- **Source:** [param087/saas-starter-skills](https://github.com/param087/saas-starter-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-param087-saas-starter-skills-project-scaffolding
- Seller: https://agentstack.voostack.com/s/param087
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.