create-woonext-app

create-woonext-app

create-woonext-app is an exclusive CLI tool for WooGraphQL Pro subscribers. It facilitates the generation of a boilerplate application for a WooGraphQL store, leveraging the power of the Next.js framework.

Prerequisites

1. Ensure nodejs and npm are installed on your system.

2. Set up a WordPress backend with the following plugins:

   • WPGraphQL v1.16 or higher
   • WooGraphQL v0.18 or higher
   • Optionally, WooGraphQL v1.4 or higher for enhanced features.

Usage

1. In your terminal, run:

   npx create-woonext-app <license> [options]
   
   <license>                      Your WooGraphQL Pro License
   
   Options:
    -h --help                     Prints CLI usage
    -v --version                  Prints CLI version
    --use-npm
   
    Explicitly tell the CLI to bootstrap the app using npm
   
    --use-pnpm
   
      Explicitly tell the CLI to bootstrap the app using pnpm
   
    --use-yarn
   
      Explicitly tell the CLI to bootstrap the app using Yarn
   
    --use-bun
   
      Explicitly tell the CLI to bootstrap the app using Bun
   
    --next-version
   
      The version of Next.js to use
   
    --app-name <name>
   
      Create the app non-interactively in <name>/ (skips the create-next-app
      name/options prompts via --yes)
   
    --local-pack <dir>
   
      Registry-free generation: skip license validation + the token .npmrc and
      install @woographql/* from the local pack's tarballs (see below)
   
    --config <woonext.json>
   
      Seed the woonext answers from a file so `woonext install` runs
      non-interactively (used with --local-pack)
   
    -- <woonext flags...>
   
      Everything after `--` is forwarded verbatim to `woonext install`
      (e.g. -- --templatesDir <dir> --packageRoot <dir> -y --disablePlugins playwright)

2. Follow the on-screen prompts:

   Create Next App prompts:

   • What is your project named? (e.g., my-app)
   • Would you like to use ESLint? (No / Yes)
   • Would you like to use src/ directory? (No / Yes)
   • Would you like to customize the default import alias? (No / Yes)
     • What import alias would you like configured? (e.g., @/*)

   WooNext install prompts:

   • What is the domain of the WordPress backend? (e.g., mysite.com)
   • What protocol is the WordPress backend using? (HTTP / HTTPS)
   • What is the WPGraphQL API endpoint? (e.g., graphql)
   • What is the name of the site? (e.g., My Store)
   • What is the description of the site? (e.g., A cool store.)
   • What product types do you want to use? (e.g., [x] Grouped / [] External / [x] Subscription / [] Bundle / [x] Composite)
   • Do you want to include account pages? (Yes / No)
   • Do you want to include an order status page? (Yes / No)

3. Once you see the Success message, navigate to your newly generated application:

   cd <project-name>

4. Start the application with:

   npm run dev

Local pack mode (registry-free)

For CI / smoke testing the CLI can generate an app without the private registry, a license, or network access, using a pre-built local pack (a directory containing the @woographql/* tarballs + a local template pack, described by a pack-manifest.json). This is how chromatic-builder exercises the full pipeline.

node create-woonext-app \
  --use-npm --app-name my-app \
  --local-pack /path/to/.woonext-pack \
  --config /path/to/woonext.json \
  -- --templatesDir /path/to/.woonext-pack/templates --packageRoot /path/to/@woographql/next -y --disablePlugins playwright

In --local-pack mode the CLI skips license validation and the token .npmrc, pins every @woographql/* dependency to its tarball via package.json overrides, copies the --config file in as woonext.json, then runs woonext install with the forwarded flags. No <license> is required.

How the Boilerplate works

The boilerplate is designed to provide a robust starting point for your WooGraphQL store:

1. Generates a Next.js app using create-next-app with TypeScript, Tailwind CSS, and App Router enabled, piping through the Create Next App CLI prompts and feedback.
2. Installs additional dependencies including some premium packages designed exclusively for applications sourcing a WooGraphQL API.
   • @woographql/react-hooks: React hooks library for managing/utilizing Session, User & Cart context for WooGraphQL powered applications.
   • @woographql/session-utils: JavaScript library for managing the lifecycles of the WPGraphQL & WooGraphQL authentication/session tokens used for identify the end-user's session and device.
   • @woographql/codegen: Wrapper for GraphQL Code Generator to furnish TypeScript typings for GraphQL responses. It also provides convenient wrappers for operations specified in the graphql/operations.graphql file. These wrappers utilize the graphql-request library to execute requests and return responses.
   • @woographql/next: A Next.js template library providing reusable and easy to modify pages, layouts, api routes, components, and utility files, along with CLIs for easy installation and other conveniences.
3. Runs the woonext install script which will prompt you about your WPGraphQL endpoint and WooGraphQL configurations before installing the generating pages, api routes, and components tailored to you WooGraphQL API.
4. woonext install initializes shadcn/ui and installs the required components based on the selected templates.

Running the dev script for the first time

When you run the dev script to thing with services are started.

• Next development server. Build the application at http://localhost:3000, unless it's in use at with case it add 1 to the port number and is hosted there, while waiting to rebuild if there are any changes to files specified by includes property in the .tsconfig file.
• GraphQL Codegen development server. Runs introspection on the GraphQL endpoint you specified in the prompts of create-woonext-app install script, and generates a /graphql/generated.ts file which will contain Typescript types for WPGraphQL schema and convenient wrappers for the operations specified in the /graphql/operations.graphql file.

If the initial page build fails for any reason confirm the GraphQL endpoint and other URLs are correct in the .env.local found in the project root. If issues persist, confirm that your WooGraphQL setting on your WordPress backend. Beyond this, you likely specified something support for something that does not exist in your WooGraphQL API during the installation script at which case you should run the reinstall script with npm run woonext:reinstall and complete the prompts and generate new applicaton files.

Access to these libraries is intrinsically linked to the developer's WooGraphQL Pro license. The CLI configures this license into the project's .npmrc file during the application generation process. If this license because invalid at any time, you would no longer be able to install/update the @woographql scoped packages. The format of this file is as follow and must live in the project root.

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

License

The create-woonext-app CLI is licensed under the MIT License.