Project Configuration

This guide covers the configuration files and environment variables in a project generated by create-woonext-app.

The CLI generates a package manager configuration file to authenticate with the private @woographql package registry. The file created depends on your package manager.

registry=https://registry.npmjs.org/
@woographql:registry=https://yeetsquad.net/
//yeetsquad.net/:_authToken="YOUR_LICENSE_KEY"
always-auth=true

npmScopes:
  woographql:
    npmAlwaysAuth: true
    npmRegistryServer: "https://yeetsquad.net/"
    npmAuthToken: "YOUR_LICENSE_KEY"

pnpm uses the same .npmrc format as npm. Additionally, pnpm projects install required peer dependencies for GraphQL code generation:

• @graphql-codegen/add
• @graphql-codegen/cli
• @graphql-codegen/typescript
• @graphql-codegen/typescript-operations
• @graphql-codegen/typescript-graphql-request
• @graphql-codegen/typescript-react-apollo

[install]
registry = "https://registry.npmjs.org"

[install.scopes]
"@woographql" = { token = "YOUR_LICENSE_KEY", url = "https://yeetsquad.net/" }

Important: These files contain your license key. Add them to .gitignore if your repository is public.

The woonext install step generates a .env.local file with your WordPress backend configuration. The key variables are:

For the complete list of environment variables and their usage, see the @woographql/next configuration docs.

The CLI auto-detects your package manager from the npm_config_user_agent environment variable. You can override this with flags:

If no flag is provided and auto-detection fails, npm is used as the default.

By default, the CLI uses the latest version of Next.js. To pin a specific version:

npx create-woonext-app YOUR_LICENSE_KEY --next-version 14.2.0

After running the CLI, your project will contain:

my-store/
├── .env.local              # WordPress endpoint configuration
├── .npmrc                  # Package registry auth (npm/pnpm)
├── .storybook/             # Storybook configuration
├── codegen.ts              # GraphQL Code Generator config
├── components.json         # shadcn/ui configuration
├── e2e/                    # Playwright end-to-end tests
├── eslint.config.mjs       # ESLint configuration
├── jest.config.ts          # Jest test configuration
├── next.config.ts          # Next.js configuration
├── playwright.config.ts    # Playwright configuration
├── woonext.json            # WooNext project configuration
├── src/                    # Source directory (optional, see below)
│   ├── proxy.ts            # NextPress proxy middleware
│   ├── actions/            # Server actions
│   ├── app/
│   │   ├── globals.css     # Global styles
│   │   ├── not-found.tsx   # 404 page
│   │   ├── (main)/         # Main storefront routes
│   │   │   ├── layout.tsx  # Main layout
│   │   │   ├── shop/       # Shop and category pages
│   │   │   ├── product/    # Single product pages
│   │   │   ├── login/      # Authentication
│   │   │   └── account/    # Customer account
│   │   ├── (wordpress)/    # WordPress-proxied routes
│   │   │   ├── layout.tsx  # WordPress layout
│   │   │   ├── page.tsx    # Home page
│   │   │   ├── cart/       # Shopping cart
│   │   │   ├── checkout/   # Checkout flow
│   │   │   └── [...uri]/   # Catch-all for WP content
│   │   └── api/            # API route handlers
│   ├── brand/              # Branding components (Logo, NavLink, etc.)
│   ├── components/ui/      # shadcn/ui primitives
│   ├── features/           # Feature-based modules
│   │   ├── account/        # Account management
│   │   ├── authentication/ # Auth flows
│   │   ├── checkout/       # Checkout logic
│   │   ├── product/        # Product display
│   │   └── shop/           # Shop/catalog
│   ├── graphql/            # GraphQL operations and generated types
│   ├── hooks/              # Custom React hooks
│   ├── layout/             # Layout components (TopNav, Footer, etc.)
│   ├── lib/                # Utility libraries
│   ├── testing/            # Test utilities
│   └── utils/              # Shared utilities
└── public/                 # Static assets

Note: The src/ directory is optional. If the --no-src-dir flag is used (or the option is deselected during setup), all contents of src/ are placed directly in the project root instead.

Only the registry config file matching your chosen package manager will be present.

The generated code is yours to own and modify. There is no runtime dependency on create-woonext-app after generation. For guidance on customizing generated components and pages, see the @woographql/next documentation.