Next.js Starter — Complete Setup Guide

This document explains:

• What we built
• Why we built it
• Architecture decisions
• npm package setup
• CLI generator setup
• Publishing process
• Best practices

Goal

Create a starter system where teams can run:

npx create-base-starter-app og-app

and instantly get:

• Next.js
• TypeScript
• SCSS Modules
• Atomic Design
• Shared architecture
• Typed setup
• Service layer
• Husky
• Lefthook
• Folder structure
• Reusable components
• Documentation

Final Architecture

We created TWO applications.

1. CLI APPLICATION

This is the npm package.

base-starter/

Purpose:

• Published to npm
• Generates projects
• Copies template
• Initializes setup

2. GENERATED NEXTJS APPLICATION

This lives inside:

templates/nextjs

Purpose:

• Real project starter
• Copied into user project
• Frontend architecture

Final Folder Structure

base-starter/
├── dist/
├── src/
├── templates/
│   └── nextjs/
├── package.json
├── tsconfig.json
├── README.md

CLI Architecture

src/index.ts

Main CLI entrypoint.

#!/usr/bin/env node

Purpose:

• Ask project name
• Copy template
• Initialize project

Why dist Exists

We use:

tsup

to compile TypeScript.

Flow:

src/index.ts
   ↓
tsup build
   ↓
dist/index.js

npm runs:

dist/index.js

NOT TypeScript directly.

Why src Should NOT Be Published

src/ is development source code only.

Users only need:

dist/

So we added:

"files": [
  "dist",
  "README.md"
]

This prevents unnecessary files from being published.

Next.js Template Setup

Inside:

templates/nextjs

we created architecture.

Enterprise Folder Structure

templates/nextjs/
├── app
├── assets
├── components
├── constants
├── hooks
├── schemas
├── services
├── shared
├── store
├── styles
├── tests
├── types
├── utils

Atomic Design

We used:

components/
├── atoms
├── molecules
├── organisms
├── templates

Benefits:

• Reusability
• Scalability
• Better UI consistency

Shared Architecture

We removed feature-based nesting and used shared architecture instead.

Example:

services/
hooks/
utils/
types/

Benefits:

• Easier onboarding
• Better discoverability
• Enterprise scalability

SCSS Setup

Each component contains:

Button/
├── Button.tsx
├── Button.types.ts
├── Button.module.scss
├── README.md
├── index.ts

Benefits:

• Typed props
• Scoped styles
• Self-documenting components

TypeScript Setup

Enabled:

"strict": true

Avoided:

any

Used:

• interfaces
• reusable types
• typed services

Service Layer Pattern

API logic isolated inside:

services/

Example:

export const getUsers = async () => {
  return apiClient.get('/users');
};

Benefits:

• Reusable APIs
• Better testing
• Clean UI components

Husky Setup

Purpose:

• Git hooks

Installed:

npm install husky --save-dev

Initialized:

npx husky init

Example hook:

npm run lint

Lefthook Setup

Purpose:

• Faster git hooks

Installed:

npm install lefthook --save-dev

Configured:

pre-commit:
  parallel: true

  commands:
    lint:
      run: npm run lint

npm Package Setup

package.json

Important fields:

{
  "bin": {
    "create-base-starter-app": "./dist/index.js"
  }
}

This creates executable CLI.

Build Setup

Used:

tsup

Build command:

"build": "tsup src/index.ts --format esm,cjs --dts && cp -R templates dist/templates"

Purpose:

• Build CLI
• Copy templates into dist

Why Templates Must Be Copied

Initially we got error:

ENOENT templates/nextjs

because published package did not include templates.

Fix:

cp -R templates dist/templates

Now templates publish correctly.

npm Publish Issues We Solved

1. Husky Not Found

Problem:

husky: command not found

Cause:

• prepare script ran before install

Fix:

"prepare": "husky || true"

2. SCSS @use Error

Problem:

@use rules must be written before any other rules

Fix:

Move all:

@use

to TOP of file.

3. TypeScript DTS Errors

Problem:

baseUrl deprecated
moduleResolution deprecated

Fix:

Updated tsconfig:

"moduleResolution": "Bundler",
"ignoreDeprecations": "6.0"

4. npm 2FA Publish Error

Problem:

403 Forbidden

Cause:

npm required token publishing.

Fix:

Created:

• Granular Access Token
• Bypass 2FA enabled

Configured:

npm config set //registry.npmjs.org/:_authToken TOKEN

5. Same Version Publish Error

Problem:

You cannot publish over previously published versions

Fix:

npm version patch

How Publishing Works

Step 1

Build package:

npm run build

Step 2

Verify package:

npm pack

Step 3

Publish:

npm publish --access public

Final Usage

Users can now run:

npx create-base-starter-app my-app

and instantly get enterprise setup.

Enterprise Benefits

Faster onboarding

New developers start immediately.

Consistent architecture

All teams follow same structure.

Reusable components

Shared design system.

Better scalability

Large applications stay maintainable.

Strong typing

Reduced runtime bugs.

Recommended Future Improvements

• TurboRepo
• Storybook
• Playwright
• Docker
• GitHub Actions
• Kubernetes configs
• Component generators
• CLI flags
• Monorepo support
• Environment generators

Recommended Commands

Local Development

npm run dev

Build Package

npm run build

Publish

npm publish --access public

Test Package Locally

npm link

then:

npx create-base-starter-app my-app

Final Notes

This setup is designed for:

• Enterprise frontend teams
• Large scale applications
• Shared engineering standards
• Long-term maintainability
• Rapid project initialization

Maintained By

Starter Frontend Architecture Team