Installation
Run Starter Free locally in minutes and explore the full SaaS surface.
OverviewLink to section
Starter Free is designed to get you from zero to a usable SaaS surface in minutes.
By the end of this guide, you will have a local product environment running with:
- auth screens
- dashboard
- projects
- admin
- billing
- settings
No database. No Stripe keys. No auth secrets.
Starter Free is intentionally mocked so you can evaluate the product surface before wiring backend services.
What Starter Free is for
Starter Free helps you validate product direction quickly with a production-shaped UI surface, without needing auth, billing, or database setup first.
What you’ll doLink to section
Run the starter
Validate routes
Start editing
PrerequisitesLink to section
Make sure your environment includes:
- Node.js 18 or newer
- pnpm
- Git
Recommended: use the latest Node.js LTS release.
node -v
pnpm -v
git --versionnpm install -g pnpmPackage manager
Starter Free is designed around pnpm. Using npm or yarn can create lockfile and dependency inconsistencies.
StepsLink to section
Clone the repositoryLink to section
Clone the starter and move into the project directory.
git clone https://github.com/pycolors-io/pycolors-starter-free.git
cd pycolors-starter-freeInstall dependenciesLink to section
Install the local baseline.
pnpm installThis installs the starter stack:
| Dependency area | Included |
|---|---|
| Framework | Next.js App Router |
| Styling | Tailwind CSS v4 |
| UI | PyColors UI |
| Language | TypeScript |
| Quality | ESLint |
Start the development serverLink to section
Run the app locally.
pnpm devThen open:
http://localhost:3000You should land on the local Starter Free product surface.
Validate the starterLink to section
Open the core routes:
/
/login
/register
/dashboard
/projects
/admin
/billing
/settingsIf the routes load correctly and navigation works, the installation is complete.
Expected behavior
Starter Free is intentionally mocked. You should be able to explore screens, layouts, and product flows immediately without backend setup or secret configuration.
First things to tryLink to section
Once the app is running, make one small product change before wiring anything.
Edit the dashboard title.
app/(app)/dashboard/page.tsxChange the heading text and save. Hot reload should update the browser instantly.
Rename the core entity.
ProjectsThe starter is intentionally easy to adapt to your own domain model.
Update the mock product data.
components/projects/project-types.tsChange the mock projects to better match your product direction.
What you should seeLink to section
At this point, you should have a local SaaS surface with:
- auth screens
- dashboard layout
- CRUD UI
- admin surface
- billing surface
- settings structure
- hot reload
Good sign
If the UI loads correctly and route navigation works, your setup is valid enough to begin product exploration and UX iteration.
Common pitfallsLink to section
Starter Free does not require:
- database URL
- auth secrets
- Stripe keys
- email provider credentials
- backend API configuration
Everything is mocked by design.
Prefer
- use pnpm consistently
- validate routes before editing
- change one product surface first
- keep mock data while exploring UX
- wire backend only after understanding the flow
Avoid
- adding database setup before the UI is understood
- using npm and pnpm in the same project
- deleting mocked flows before exploring them
- rewriting layout before validating product structure
- treating Starter Free like a complete backend template
TroubleshootingLink to section
Next stepsLink to section
Upgrade when wiring becomes the blocker
Starter Free validates the product surface. Starter Pro wires the business layer with production-shaped auth, billing, backend, and delivery foundations. → /docs/starter-pro