Quickstart Instructions

Prerequisites

1. Have the Yext CLI installed: https://hitchhikers.yext.com/guides/cli-getting-started-resources/01-install-cli/

2. Have Deno installed, version 1.41.3: https://deno.land/manual/getting_started/installation

3. Have node installed, version 18.20.0: https://nodejs.org/en/download/

   • It's recommend to use nvm: https://github.com/nvm-sh/nvm#installing-and-updating or via brew brew install nvm

4. Have a Yext account (necessary for production builds, deploying on Yext Sites, and pulling local stream document data).

Getting started

1. Clone this repo and install dependencies:

   git clone https://github.com/yext-pages/react-kourakuen-stores.git
   cd react-kourakuen-stores
   npm install

2. Run yext init and authenticate the CLI with your Yext credentials.

3. You’re good to go! Run npm run dev to spin up a local development server and take a look at your starter site.

Useful commands

yext init - Authenticates the Yext CLI with your Yext account

npm install - Download and install all the dependencies specified in the package.json file. You should run this command when you first clone a project repository, after modifying dependencies in the package.json file, or if you've deleted the node_modules folder and need to reinstall all packages.

npm run dev - runs your code against a local dev server using Vite

npm run build - Runs a production build against your localData

npm run prod - Runs a local server against your production-built files

• It's recommended to npm run build followed by npm run prod before committing in order to test that a real production build won't have any issues. In practice, development builds (via npm run dev) and production builds compile and bundle assets differently. For local development, ES Modules are loaded directly by the browser, allowing fast iteration during local development and also allows for hot module replacement (HMR). Other things like CSS are also loaded directly by the browser, including linking to sourcemaps. During a production build all of the different files are compiled (via ESBuild for jsx/tsx) and minified, creating assets as small as possible so that the final html files load quickly when served to a user.

npm run fmt - Automatically formats all code

npm run lint - Run ESLint to check for errors and warnings

Repository Layout

root
└───localData
└───src
│   │   index.css
│   │
│   └───components
│   │
│   └───layouts
│       │   main.tsx
│   │
│   └───templates
│       │   index.tsx
│       │   static.tsx
│   │
│   └───types

localData

Contains example stream documents that are used while local developing. By default this repo contains example files that work with the provided example templates. You can generate real stream documents specific to your Yext account via yext sites generate-test-data.

NOTE: You normally wouldn't want to check in the localData folder as it's only used for local dev. It is gitignored by default.

src

components

This is where all of your custom components may live. This folder is not required and you can set up your own custom folder structure for your own components in any way you'd like, as long as it lives in the src directory.

layouts

This is where wrapper components may live. Like /components this folder is not required, and only serves organizational benefits. Layouts help encapsulate top level components across templates. A top level component can be a header, footer, react context, or anything else you'd like to preserve across multiple templates.

templates

Required. This is where your actual templates live. There are effectively two types of components:

1. stream-based templates: those that have an exported config
2. static templates: those that don't have an exported config. Furthermore, they may also export a getStaticProps function if external data is required.

NOTE: It's not currently possible to generate multiple html files using a static template, even if getStaticProps returns arrayed data.

types

Here you can define any custom TypeScript types you need.

index.css

Not required. In this example this sets up Tailwind CSS.

vite.config.js

Vite is now a first class member of the starter! This file defines any custom Vite configuration you want, giving you full control over your setup. Specifically, it will allows users to pass additional configuration options to the vite-plugin-yext-sites-ssg plugin when they become more widely available.

Everything else

The rest of the files are basic config setup common to many other React projects. In this example we've enabled:

1. Tailwind CSS (which leverages PostCSS) - used for easy styling
2. ESLint - catches errors in your code
3. Prettier - formats your code (you can add .prettierrc to override any default settings)
4. TypeScript - adds typing to Javascript for a better developer experience