docs: creating storefront (#157)

* docs: running storefront locally

* docs: using app keys

* docs: env vars placeholder

* docs: simple troubleshooting

* docs: updated intro

* docs: storefront deployment with vercel wip

apps/composable-cli-docs/docs/build-a-storefront.mdx

@@ -29,6 +29,14 @@ Application keys are used to directly manage access to Organizations and stores.
 
 You can use application keys to generate client_credentials and implicit tokens. To learn more about client_credentials and implicit tokens, see [Security](https://elasticpath.dev/docs/commerce-cloud/authentication/security).
 
+The application key consists of two parts a client_id (client-side) and client_secret (server-side).
+
+:::warning WARNING
+
+**Do not use the client_secret in a client-side application.** The client_secret is intended to be used in a server-side application and will grant access to administrator level APIs on your store.
+
+:::
+
 There are two ways to create an application key:
 
 1. Using the Elastic Path Commerce Manager
@@ -44,7 +52,7 @@ In a Commerce store, all organization and store admins can create, view, and man
 4. In the **Name** field, enter the name of the key that you want.
 5. Click **Create**
 
-:::tip My tip
+:::tip TIP
 
 Make sure to copy your Client Secret key and save it somewhere secure because your Client Secret key will be not be displayed to you again.
 
@@ -89,7 +97,8 @@ To create an application key using the Elastic Path API use the `/v2/application
   </TabItem>
 </Tabs>
 
-After creating the application key you can use the client_id to create the `implicit` access token you need. The JS SDK will do this for you automatically, but if you are using the API directly you will need to call the [authentication endpoint](https://elasticpath.dev/docs/commerce-cloud/authentication/Tokens/implicit-token) to get the token.
+## Using the application key in storefront
 
-### Using the key in storefront
+After creating the application key you can use the client_id to create the `implicit` access token you need. The JS SDK will do this for you automatically, but if you are using the API directly you will need to call the [authentication endpoint](https://elasticpath.dev/docs/commerce-cloud/authentication/Tokens/implicit-token) to get the token.
 
+[How to use application keys in your storefront](/docs/concepts/use-application-keys-storefront)

apps/composable-cli-docs/docs/composable-starter/deploy/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Deploy",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Composable starter storefront deployment instructions"
+  }
+}

apps/composable-cli-docs/docs/composable-starter/deploy/storefront-deploy.mdx

@@ -0,0 +1,207 @@
+---
+sidebar_position: 1
+title: Deployment on Vercel
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Deploying your storefront on Vercel
+
+The storefront generated by Composable CLI is ready to deploy to any Next.js supporting hosting provider.
+
+The following is a quick guide to deploying the Composable Starter to Vercel using the Vercel CLI. For more detailed information about features and additional functionality, see the [Vercel documentation](https://vercel.com/docs/cli).
+
+## Pre-requisites
+
+### Generated storefront
+
+You will need to have generated a storefront using the Composable CLI. If you haven't done this yet, you can follow the [getting started guide](/docs/composable-starter/storefront-starter) to generate a storefront.
+
+### Required Accounts
+
+- [Vercel Account](https://vercel.com/signup)
+- [GitHub Account](https://github.com/signup): only required if you want to use GitHub continuous deployment
+
+### Required tooling
+- [Git and Git CLI](https://git-scm.com/): only required if you want to use GitHub continuous deployment
+
+## Deployment Options
+
+Once you have a Vercel account, you can deploy your storefront by using the Vercel CLI or GitHub and Vercel continuous deployment see the instruction below.
+
+- [Deploying to Vercel using GitHub continuous deployment](#deploying-to-vercel-using-github-continuous-deployment)
+- [Deploying to Vercel using the Vercel CLI](#deploying-to-vercel-using-the-vercel-cli)
+
+## Deploying to Vercel using GitHub continuous deployment
+
+The following is a quick guide to deploying the Composable Starter to Vercel using GitHub.
+
+### Step 1: Create a GitHub repository
+
+Before you can deploy, you need to create a GitHub repository and push the starter codebase to it:
+
+1. On GitHub, click the plus icon at the top right, then click New Repository.
+2. You’ll then be redirected to a new page with a form. In the form, enter the Repository Name.
+3. Scroll down and click Create repository.
+
+more information about creating a GitHub repository can be found [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories).
+
+#### Push the starter codebase to GitHub
+
+Now that you have an empty repository the next step is to push the starter codebase to GitHub.
+
+Looking at the repository page on GitHub you should see a URL that you can copy to connect to the repository e.g. `https://github.com/<your-account>/<your-repo>.git`
+
+A local repository should have been initialized when you generated your storefront. If not, you can initialize a local repository by running the following command in the root of your storefront directory:
+
+```bash
+git init
+git add .
+git commit -m "initial commit"
+```
+
+Now in your terminal run the following command to connect your local repository to the GitHub repository you just created:
+
+```bash
+git remote add origin https://github.com/<your-account>/<your-repo>.git
+```
+
+making sure to replace `https://github.com/<your-account>/<your-repo>.git` with your repository URL.
+
+Finally, push the starter codebase to GitHub by running the following command:
+
+```bash
+git push origin main
+```
+
+After the push is complete, you should see the starter codebase in your GitHub repository.
+
+### Step 2: Deploy using Vercel Dashboard
+
+1. Login to your Vercel account and load the [dashboard](https://vercel.com/dashboard).
+2. Click on "Add new..."
+3. Choose project from the dropdown
+4. In the Import page that opens, find the Git repository you just created and click Import. Make sure you have connected Vercel to your GitHub account first.
+5. In the Configure Project form:
+    - Optionally change the projects name.
+    - Open the "Environment Variables" section:
+         - Add the environment variables to match your local environment. You can find these in the `.env.local` file in the root of your storefront directory. e.g. `NEXT_PUBLIC_EPCC_CLIENT_ID`, `NEXT_PUBLIC_PASSWORD_PROFILE_ID` etc
+         - Instead of entering them individually, you can copy the contents of the file and paste it into the "Key" input on the form for all values to populate.
+6. Once all the settings are correct, click Deploy.
+
+This will start the deployment of the Composable Starter. Once it’s done, you’ll be redirected to the main dashboard of your new project.
+
+## Deploying to Vercel using the Vercel CLI
+
+### Install the Vercel CLI
+
+To install the Vercel CLI globally, run the following command:
+
+<Tabs>
+  <TabItem value="npm" label="NPM">
+
+    ```bash
+    npm i -g vercel
+    ```
+
+  </TabItem>
+  <TabItem value="pnpm" label="PNPM">
+
+    ```bash
+    pnpm i -g vercel
+    ```
+
+  </TabItem>
+  <TabItem value="yarn" label="YARN">
+
+    ```bash
+    yarn global add vercel
+    ```
+
+  </TabItem>
+</Tabs>
+
+You can confirm it installed correctly by running:
+
+```bash
+vercel --version
+```
+
+this should output something like below but with your installed version:
+
+```bash
+Vercel CLI 29.0.0
+29.0.0
+```
+
+### Login to Vercel CLI
+
+To login to the Vercel CLI, run the following command:
+
+```bash
+vercel login
+```
+
+follow the prompts to login to your Vercel account.
+
+### Create and link a project
+
+Vercel projects are the top level container for your deployments. To create a project, run the following command with a project name of your choice:
+
+```bash
+vercel project add my-project
+```
+You can learn more about Vercels project command [here](https://vercel.com/docs/cli/project).
+
+Link the project to your storefront by running the following command in your storefront directory and when prompted for the project name, enter the name you used in the previous step:
+
+```bash
+vercel link
+```
+
+You should get a message to confirm the project has been linked. If there is any issues getting the project linked you can have a look at the [Vercel CLI docs](https://vercel.com/docs/cli/linking).
+
+### Setting environment variables
+
+The project needs to have the appropriate environment variables set to be able to deploy your storefront. There are different ways to set environment variables in Vercel projects:
+
+- [Using the Vercel dashboard (recommended)](#using-the-vercel-dashboard)
+- [Using the Vercel CLI](#using-the-vercel-dashboard)
+
+:::tip
+The environment variables you need to match your local environment in Vercel are located in the `.env.local` file in the root of your storefront directory.
+:::
+
+#### Using the Vercel dashboard
+
+Follow the instructions in the [Vercel docs](https://vercel.com/docs/projects/environment-variables#declare-an-environment-variable) to add the following environment variables from your `.env.local` to your project.
+
+
+#### Using the Vercel CLI
+
+:::warning
+At this time there is no built-in way to add multiple environment variables at once using the Vercel CLI see [this issue](https://github.com/vercel/vercel/discussions/4977). You can use the [Vercel dashboard](https://vercel.com/dashboard) to add multiple environment variables at once.
+:::
+
+To set environment variables using the Vercel CLI, run the following command:
+
+```bash
+vercel env add NEXT_PUBLIC_EPCC_CLIENT_ID
+```
+
+where `NEXT_PUBLIC_EPCC_CLIENT_ID` is the name of the environment variable you want to set. You will be prompted to enter the value for the environment variable and what environments you want to set it for.
+
+Frustratingly it's not currently possible to set multiple environment variables at once using the Vercel CLI. The above process will have to be repeated for each environment variable that we have to set. Alternatively you can use the [Vercel dashboard](https://vercel.com/dashboard) to add multiple environment variables at once.
+
+### Deploy storefront to Vercel
+
+Lastly we need to deploy the storefront to Vercel. To do this run the following command in your storefront directory:
+
+```bash
+  vercel deploy
+```
+
+The storefront will be built and deployed to Vercel. Once the deployment is complete you will be given a URL to access your storefront.
+
+more information can be found from the [Vercel cli docs](https://vercel.com/docs/cli/deploying-from-cli)

apps/composable-cli-docs/docs/composable-starter/storefront-starter.mdx

@@ -21,15 +21,15 @@ You’re going to complete the following tasks:
 
 ## Prerequisites
 
-- Node.js v18.17+
+- Node.js v18 or later
 - You've installed a Node.js package manager: either [npm](https://www.npmjs.com/get-npm), [Yarn 1.x](https://classic.yarnpkg.com/lang/en/docs/install), or [pnpm](https://pnpm.io/installation).
-- composable-cli v0.10.2+
+- Latest [composable-cli](https://www.npmjs.com/package/composable-cli)
 - You've installed [Git](https://git-scm.com/)
 
 ### Elastic Path account
 You'll also need an Elastic Path account to access the backend. If you don't have one, you can [sign up for a free trial](https://useast.cm.elasticpath.com/free-trial).
 
-### Install globally and authenticate with Composable CLI
+### Install Composable CLI globally and authenticate
 
 You'll need to install the latest version of composable-cli to get started. You can do this by running the following command:
 
@@ -73,3 +73,35 @@ In your terminal, run the following command to create a new Composable Starter a
 ```bash
 ep generate d2c my-storefront
 ```
+
+## Running the storefront locally
+
+The Composable Starter app is built on top of [Next.js](https://nextjs.org/). Your local developer experience will be the same as any Next.js app. To learn more about Next.js, see the [Next.js documentation](https://nextjs.org/docs).
+
+To run your storefront locally, run the following command from your project directory:
+
+<Tabs>
+  <TabItem value="npm" label="NPM">
+
+    ```bash
+    npm run dev
+    ```
+
+  </TabItem>
+  <TabItem value="pnpm" label="PNPM">
+
+    ```bash
+    pnpm dev
+    ```
+
+  </TabItem>
+  <TabItem value="yarn" label="YARN">
+
+    ```bash
+    yarn dev
+    ```
+
+  </TabItem>
+</Tabs>
+
+Your Next.js Elastic Path powered storefront will run at `http://localhost:3000` (look at the terminal output for the exact URL as your local environment may be different).

apps/composable-cli-docs/docs/composable-starter/troubleshooting.mdx

@@ -0,0 +1,26 @@
+---
+sidebar_position: 3
+title: Troubleshooting
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Failed configuration tasks
+One of my configuration tasks failed. What should I do?
+
+If one or more of your configuration tasks failed you can retry them by running the appropriate CLI command from your project directory:
+
+e.g. Algolia configuration:
+
+```bash
+ep int algolia
+```
+
+e.g. Elastic Path Payments configuration:
+
+```bash
+ep payments ep-payments
+```
+
+full list of available configuration tasks can be found in the [Composable CLI docs](/docs/composable-cli/commands).

apps/composable-cli-docs/docs/concepts/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Concepts",
+  "position": 3.5,
+  "link": {
+    "type": "generated-index",
+    "description": "Elastic Path front end concepts"
+  }
+}

apps/composable-cli-docs/docs/concepts/storefront-environment-variable.mdx

@@ -0,0 +1,10 @@
+---
+sidebar_position: 2
+title: "Storefront: Environment Setup"
+---
+
+## Understanding the .env.local file
+
+:::warning
+Coming soon
+:::