sfnext-project-setup

Project Setup Skill

This skill guides you through creating and configuring a Storefront Next project — a server-rendered SPA built on React 19, React Router 7, Vite, and Tailwind CSS v4.

Overview

Storefront Next storefronts run on Managed Runtime (MRT) with all SCAPI requests executing server-side. Projects are created with create-storefront from @salesforce/storefront-next-dev and use TypeScript exclusively (.ts/.tsx files only — .js/.jsx/.mjs/.cjs are forbidden).

Creating a Project

Via CLI (local development)

# Create a new storefront project (interactive)
pnpm dlx @salesforce/storefront-next-dev create-storefront

# Or create with a name flag
pnpm dlx @salesforce/storefront-next-dev create-storefront --name my-storefront

# Navigate into the project
cd my-storefront

# Install dependencies
pnpm install

# Start development server
pnpm dev

Via Business Manager

Projects can also be created from Business Manager, which sets up the storefront with Commerce Cloud credentials pre-configured.

Project Structure

my-storefront/
├── .env.default              # Default environment variables (template)
├── .env                      # Local overrides (git-ignored)
├── config.server.ts          # Centralized configuration with defaults
├── vite.config.ts            # Vite build configuration
├── package.json              # Dependencies and scripts
├── src/
│   ├── app.css               # Global styles and Tailwind theme
│   ├── root.tsx              # Root layout component
│   ├── routes/               # File-based routes (React Router 7)
│   │   ├── _app.tsx          # App layout (authenticated shell)
│   │   ├── _app._index.tsx   # Home page
│   │   └── _app.product.$productId.tsx
│   ├── components/           # Reusable UI components
│   │   ├── ui/               # shadcn/ui base components (customizable)
│   │   └── ...               # Custom components
│   ├── config/               # Configuration schema and context
│   │   └── schema.ts         # Config type definitions
│   ├── lib/                  # Utilities and API client setup
│   │   ├── api-clients.ts    # createApiClients() factory
│   │   ├── utils.ts          # cn() utility and helpers
│   │   └── registry.ts       # Page Designer component registry
│   ├── locales/              # Translation files
│   │   └── en-US/
│   │       └── translations.json
│   ├── middlewares/          # Server middleware
│   │   ├── auth.server.ts    # Authentication middleware
│   │   └── basket.server.ts  # Basket middleware
│   ├── providers/            # React context providers
│   ├── hooks/                # Custom React hooks
│   ├── extensions/           # Extension modules
│   └── test-utils/           # Shared test utilities
├── public/                   # Static assets
└── cartridges/               # Page Designer cartridge metadata

See Project Structure Reference for detailed directory explanations.

Environment Setup

Copy .env.default to .env and configure required Commerce Cloud credentials:

cp .env.default .env

Required Variables

PUBLIC__app__commerce__api__clientId=your-client-id
PUBLIC__app__commerce__api__organizationId=your-org-id
PUBLIC__app__commerce__api__siteId=your-site-id
PUBLIC__app__commerce__api__shortCode=your-short-code
PUBLIC__app__defaultSiteId=your-site-id
PUBLIC__app__commerce__sites='[{"id":"your-site-id","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"}],"supportedCurrencies":["USD"]}]'

See Environment Variables Reference for the complete variable list and naming rules.

Development Commands

# Start development server with hot reload
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Run Storybook
pnpm storybook

# Check bundle size
pnpm bundlesize:test

Non-Negotiable Rules

1. TypeScript only — .ts and .tsx files; JavaScript files are blocked by ESLint
2. Server-only data loading — Use loader functions; never use client loaders
3. Synchronous loaders — Return promises, do not use async/await (enables streaming)
4. Tailwind CSS 4 only — No inline styles, CSS modules, or separate CSS files
5. Use createPage() HOC — Standardizes page patterns with Suspense

Troubleshooting

Issue	Cause	Solution
SCAPI 401 errors	Missing or invalid credentials	Verify .env variables match your Commerce Cloud org
JavaScript file errors	.js/.jsx files in source	Rename to .ts/.tsx; ESLint blocks JS files
Dev server not starting	Missing dependencies	Run pnpm install
Config not loading	Missing config.server.ts defaults	Define defaults before using environment overrides

Related Skills

• storefront-next:sfnext-configuration - Ongoing configuration management and multi-site setup
• storefront-next:sfnext-routing - File-based routing conventions
• storefront-next:sfnext-data-fetching - Server-side data loading patterns
• storefront-next:sfnext-deployment - Building and deploying to MRT

Reference Documentation

• Project Structure Reference - Detailed directory and file explanations
• Environment Variables Reference - Complete variable list and naming rules