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. 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](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-bm-github.html) or [local-code workflow](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-bm.html). 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. ```bash # 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](references/PROJECT-STRUCTURE.md) for detailed directory explanations. ## Environment Setup For Business Manager-created storefronts, use the downloaded configuration. For local CLI exploration, copy `.env.default` to `.env`: ```bash 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](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html) for public/server-only visibility and supported paths. ```bash 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](references/ENV-VARIABLES.md) for the complete variable list and naming rules. ## Development Commands ```bash # 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](references/PROJECT-STRUCTURE.md) - Detailed directory and file explanations - [Environment Variables Reference](references/ENV-VARIABLES.md) - Complete variable list and naming rules