Agent Skills: Project Setup Skill

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. Use Business Manager storefront setup for an instance-connected storefront; use create-storefront for local exploration. Project application source uses TypeScript (.ts/.tsx); follow the project's configuration for build scripts.

Creating a Project

Via Business Manager (instance-connected storefront)

Prefer storefront setup: it creates API clients, MRT resources, initial configuration, and a deployment. Reuse those resources; do not create replacement SLAS clients or MRT projects as routine setup. Choose the GitHub workflow or local-code workflow. Use the downloaded env.txt as the project's .env; do not invent tenant/site IDs or expose its secrets. Guide the user through Business Manager when setup is needed.

Via CLI (local exploration)

Use for template exploration without provisioning instance resources. To connect to the user's instance, follow storefront setup above and use its configuration.

# 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

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

For Business Manager-created storefronts, use the downloaded configuration. For local CLI exploration, copy .env.default to .env:

cp .env.default .env

Required Variables

Use values from the selected storefront. This is a configuration example, not a request to provision new credentials. See Salesforce's Environment Variables for public/server-only visibility and supported paths.

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