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

2. Follow the on-screen 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., @/*)
   • Which style would you like to use? (Default / New York)
   • Which color would you like to use as base color? (Slate / Gray / Neutral / Stone / Zinc)
   • Do you want to use CSS variables for colors? (Yes / No)
   • 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 ~ Experimental: WIP? (Yes / No)
   • Do you want to include an order status page ~ Experimental: WIP? (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

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 npx create-next-app@latest -y --ts, 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 designed for Next 13 providing reusable and easy to modify pages, layouts, api routes, components, and utility files, along with CLIs for easy installation and other conveniences.
3. Installs shadcn/ui configuration prompting you for any information that wasn't taken in the Next.js prompts, then installs components to the /ui directory.
   • accordion
   • aspect-ratio
   • badge
   • button
   • card
   • checkbox
   • collapsible
   • form
   • input
   • label
   • progress
   • radio-group
   • select
   • sheet
   • slider
   • tabs
   • toast
4. 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.

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.