docs: updated next.js starter docs (medusajs#5748)

shahednasser · web-flow · commit deca78f74928 · 2023-11-28T09:42:28.000Z
* docs: updated next.js starter docs

* fix lint errors

* added migration script
diff --git a/www/apps/docs/content/plugins/search/meilisearch.md b/www/apps/docs/content/plugins/search/meilisearch.md
@@ -13,7 +13,7 @@ In this document, you’ll learn how to install the [MeiliSearch plugin](https:/
 
 MeiliSearch also provides a pleasant developer experience, as it is extremely intuitive and newcomer-friendly. So, even if you're new to the search engine ecosystem, [their documentation](https://docs.meilisearch.com/) is resourceful enough for everyone to go through and understand.
 
-Through Medusa's flexible plugin system, it is possible to add a search engine to your Medusa backend and storefront using MeiliSearch with just a few steps.
+Through Medusa's flexible plugin system, it's possible to add a search engine to your Medusa backend and storefront using MeiliSearch with just a few steps.
 
 ---
 
@@ -27,7 +27,7 @@ It is required to have a Medusa backend installed before starting with this docu
 
 You must install MeiliSearch to use it with Medusa. You can follow [this documentation to install MeiliSearch](https://docs.meilisearch.com/learn/getting_started/quick_start.html#setup-and-installation) either locally or on a cloud.
 
-Furthermore, you should create a master key for your MeiliSearch instance. If you don’t have one created, follow [this guide](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance) to create a master key.
+Furthermore, you should create a master key for your MeiliSearch instance. If you don’t have one created, follow [this guide](https://www.meilisearch.com/docs/learn/security/master_api_keys#protecting-a-meilisearch-instance) to create a master key.
 
 ---
 
@@ -46,9 +46,10 @@ MEILISEARCH_HOST=<YOUR_MEILISEARCH_HOST>
 MEILISEARCH_API_KEY=<YOUR_MASTER_KEY>
 ```
 
-Where `<YOUR_MEILISEARCH_HOST>` is the host of your MeiliSearch instance. By default, if MeiliSearch is installed locally, the host is `http://127.0.0.1:7700`.
+Where:
 
-`<YOUR_MASTER_KEY>` is the master key of your MeiliSearch instance.
+- `<YOUR_MEILISEARCH_HOST>` is the host of your MeiliSearch instance. By default, if MeiliSearch is installed locally, the host is `http://127.0.0.1:7700`.
+- `<YOUR_MASTER_KEY>` is the master key of your MeiliSearch instance.
 
 Finally, in `medusa-config.js` add the following item into the `plugins` array:
 
@@ -90,7 +91,10 @@ const plugins = [
           displayedAttributes,
         },
         primaryKey,
-        transformer,
+        transformer: (product) => ({
+          id: product.id, 
+          // other attributes...
+        }),
       },
     },
     },
@@ -141,10 +145,6 @@ const plugins = [
             ],
           },
           primaryKey: "id",
-          transformer: (product) => ({
-            id: product.id, 
-            // other attributes...
-          }),
         },
       },
     },
diff --git a/www/apps/docs/content/starters/nextjs-medusa-starter.mdx b/www/apps/docs/content/starters/nextjs-medusa-starter.mdx
@@ -141,60 +141,31 @@ Your Next.js Starter Storefront is now running at `localhost:8000`
 
 ---
 
-## Development Notes
-
-### Changing Medusa Backend URL
-
-By default, the Medusa backend runs at `http://localhost:9000`. This value is defined in your Next.js starter Storefront under the environment variable `NEXT_PUBLIC_MEDUSA_BACKEND_URL`.
-
-If you need to change the URL of your Medusa backend because you changed the backend's default port or because you deployed your backend, change the value of `NEXT_PUBLIC_MEDUSA_BACKEND_URL` (typically in `.env.local`) to your backend URL. For example:
-
-```bash
-NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9001
-```
-
-### Using Product Module
-
-:::note
-
-The Product Module is currently in beta. You can learn more about it [here](../experimental/product/install-nodejs.md). In addition, the product module in the Next.js storefront can't be used without the Medusa backend at the moment.
-
-:::
+## Storefront Features
 
-This starter has full support for the serverless Product Module for retrieving and manipulating product data directly from a serverless function. This keeps your product logic close to the frontend, making it easy to customize or extend Medusa's core functionality from within your Next.js project.
+### Featured products on homepage
 
-By default, this starter uses the standard Medusa API for product and collection retrieval.
+Your store's products are showcased on the homepage. If you don't see any products, make sure to [create collections and add products to them](../user-guide/products/collections.mdx).
 
-To enable the Product Module, first, make sure to set the following environment variables:
+![Featured products on the homepage](https://res.cloudinary.com/dza7lstvk/image/upload/v1701115394/Medusa%20Docs/Screenshots/Screenshot_2023-11-27_at_8.03.02_PM_ekystg.png)
 
-- `PRODUCT_POSTGRES_URL`: the URL of your PostgreSQL databsae.
-- `NEXT_PUBLIC_BASE_URL`: the URL of your storefront's base URL. For exmaple, if you're running it locally, it should be `http://localhost:8000`.
+### View all products and manage your cart
 
-Then, enable the `productModule` feature flag in `store.config.json`:
+![All Products Page](https://res.cloudinary.com/dza7lstvk/image/upload/v1701115070/Medusa%20Docs/Screenshots/Screenshot_2023-11-27_at_7.40.04_PM_hnmbwa.png)
 
-```json title="store.config.json"
-{
-  "features": {
-    // other features...
-    "productModule": true
-  }
-}
-
-```
+### Customer authentication and profiles
 
-You can now test it out now. Make sure the Medusa backend is running, then start (or restart) your Next.js storefront:
+![Customer Profile](https://res.cloudinary.com/dza7lstvk/image/upload/v1701115136/Medusa%20Docs/Screenshots/Screenshot_2023-11-27_at_7.58.43_PM_xfdnnp.png)
 
-```bash npm2yarn
-npm run start
-```
+### Full checkout workflow
 
-If you go to `localhost:8000`, all product and collection data should now be coming from the module. The Product Module routes are all in the `src/app/api` directory for you to customize to your use case.
+![Checkout Page](https://res.cloudinary.com/dza7lstvk/image/upload/v1701115205/Medusa%20Docs/Screenshots/Screenshot_2023-11-27_at_7.59.55_PM_psdjwq.png)
 
-To opt out of using the product module, simply set the `productModule` feature flag in `store.config.json` to `false` and restart the server.
+---
 
-### Toggle Search Engine Feature
+## Toggle Search Engine Feature
 
-The Next.js Starter Storefront by default is compatible with MeiliSearch.
+The Next.js Starter Storefront by default is compatible with the MeiliSearch plugin.
 
 To enable or disable the search engine, change the value of the feature in `store.config.json`:
 
@@ -206,25 +177,25 @@ To enable or disable the search engine, change the value of the feature in `stor
 }
 ```
 
-Then, restart your Next.js backend. Depending on whether you enabled or disabled the search engine, the search bar will appear or disappear in the navigation bar accordingly.
+Then, restart your Next.js backend. Depending on whether you enabled or disabled the search engine, the "Search" link in the navigation bar will appear or disappear accordingly.
 
 ### MeiliSearch Integration
 
-If you have the search engine feature enabled, it is expected that you have installed the MeiliSearch plugin on your Medusa backend. If not, [follow this guide to install it](../plugins/search/meilisearch.md).
+If you have the search engine feature enabled, it's expected that you have installed the MeiliSearch plugin on your Medusa backend. If not, [follow this guide to install it](../plugins/search/meilisearch.md).
 
 In your Next.js Starter Storefront, set the environment variables necessary for the MeiliSearch integration:
 
 ```json
 NEXT_PUBLIC_SEARCH_ENDPOINT=<YOUR_MEILISEARCH_URL>
-NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_API_KEY>
 NEXT_PUBLIC_INDEX_NAME=products
+NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_API_KEY>
 ```
 
-`<YOUR_MEILISEARCH_URL>` is the URL MeiliSearch is running on. The default is `http://127.0.0.1:7700`.
-
-`NEXT_PUBLIC_INDEX_NAME` is the index name of the products in MeiliSearch. By default, it’s `products`.
+Where:
 
-`<YOUR_API_KEY>` is the API key used to search through MeiliSearch indexes. To create a new API Key, make sure that the MeiliSearch service is running and send the following request:
+- `<YOUR_MEILISEARCH_URL>` is the URL MeiliSearch is running on. The default is `http://127.0.0.1:7700`.
+- `NEXT_PUBLIC_INDEX_NAME` is the index name of the products in MeiliSearch. By default, it’s `products`.
+- `<YOUR_API_KEY>` is the API key used to search through MeiliSearch indexes. To create a new API Key, make sure that the MeiliSearch service is running and send the following request:
 
 ```bash
 curl \
@@ -239,33 +210,40 @@ curl \
   }'
 ```
 
-Make sure to replace `<MEILISEARCH_URL>` with the URL MeiliSearch is running on and `<MEILISEARCH_MASTER_KEY>` with your MeiliSearch [master key](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance).
+Make sure to replace `<MEILISEARCH_URL>` with the URL MeiliSearch is running on and `<MEILISEARCH_MASTER_KEY>` with your MeiliSearch [master key](https://www.meilisearch.com/docs/learn/security/master_api_keys#protecting-a-meilisearch-instance).
 
-Then, restart the Next.js backend. You’ll be able to search through available products by clicking the search icon in the navigation bar.
+Then, restart the Next.js storefront. You’ll be able to search through available products by clicking the search icon in the navigation bar.
 
-:::note
+:::tip
 
-To make sure the Next.js Starter Storefront properly displays the products in the search result, include in the `displayedAttributes` setting of the MeiliSearch plugin on the Medusa backend at least the fields `title`, `handle`, `description`, and `thumbnail`.
+To make sure the Next.js Storefront properly displays the products in the search result, include in the `displayedAttributes` setting of the MeiliSearch plugin on the Medusa backend at least the fields `title`, `handle`, `description`, and `thumbnail`.
 
 :::
 
-![Search Result on Next.js Starter Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003191/Medusa%20Docs/Screenshots/gQVWvH2_h1ljig.png)
+![Search Result on Next.js Starter Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1701112725/Medusa%20Docs/Screenshots/Screenshot_2023-11-27_at_7.18.09_PM_iozjt0.png)
 
 ### Algolia Integration
 
 Instead of using the default MeiliSearch search engine, you can switch to using Algolia. Make sure you start by installing the Algolia plugin on your Medusa backend. You can do it by [following this guide](../plugins/search/algolia.md).
 
-In your Next.js Starter Storefront, set the environment variables necessary for the Algolia integration:
+In your Next.js Starter Storefront, install the `algoliasearch` package in your Next.js storefront:
+
+```bash npm2yarn
+npm install algoliasearch
+```
+
+Then, set the environment variables necessary for the Algolia integration:
 
 ```bash
 NEXT_PUBLIC_SEARCH_APP_ID=<YOUR_APP_ID>
 NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_SEARCH_API_KEY>
 NEXT_PUBLIC_INDEX_NAME=products
 ```
 
-Where `<YOUR_APP_ID>` and `<YOUR_SEARCH_API_KEY>` are the Algolia App ID and Algolia Search API Key respectively. You can retrieve them from Algolia by going to [API Keys](https://www.algolia.com/account/api-keys/all) in your account settings.
+Where:
 
-`NEXT_PUBLIC_INDEX_NAME` is the index name of the products in Algolia. By default, it’s `products`.
+- `<YOUR_APP_ID>` and `<YOUR_SEARCH_API_KEY>` are the Algolia App ID and Algolia Search API Key respectively. You can retrieve them from Algolia by going to [API Keys](https://www.algolia.com/account/api-keys/all) in your account settings.
+- `NEXT_PUBLIC_INDEX_NAME` is the index name of the products in Algolia. By default, it’s `products`.
 
 Next, change the content of `src/lib/search-client.ts` to the following:
 
@@ -282,9 +260,35 @@ export const SEARCH_INDEX_NAME =
   process.env.NEXT_PUBLIC_INDEX_NAME || "products"
 ```
 
-Then, restart the Next.js backend. You’ll be able to search through available products by clicking the search icon in the navigation bar.
+Next, change the content of `src/app/(main)/search/actions.ts` to the following:
+
+```ts title="src/app/(main)/search/actions.ts"
+"use server"
+
+import { 
+  searchClient,
+  SEARCH_INDEX_NAME,
+} from "@lib/search-client"
+
+/**
+ * Uses MeiliSearch or Algolia to search for a query
+ * @param {string} query - search query
+ */
+export async function search(query: string) {
+  const index = searchClient.initIndex(SEARCH_INDEX_NAME)
+  const { hits } = await index.search(query)
+
+  return hits
+}
+```
 
-![Search Pop-up in Next.js Starter Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003205/Medusa%20Docs/Screenshots/ZLgX5Ad_po6a4n.png)
+Finally, restart the Next.js backend. You’ll be able to search through available products by clicking the search icon in the navigation bar.
+
+![Search Pop-up in Next.js Starter Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1701112725/Medusa%20Docs/Screenshots/Screenshot_2023-11-27_at_7.18.09_PM_iozjt0.png)
+
+---
+
+## Payment Integrations
 
 ### Stripe Payment Integration
 
@@ -300,8 +304,6 @@ Make sure to replace `<YOUR_PUBLISHABLE_KEY>` with your Stripe publishable key.
 
 If you restart your Next.js backend you should be able to pay with Stripe on checkout.
 
-![Pay with Stripe on Checkout](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003250/Medusa%20Docs/Screenshots/h5mWdJT_yjogcq.png)
-
 ### PayPal Payment Integration
 
 PayPal integration is supported by default. Make sure you have PayPal installed and enabled on your Medusa backend first. You can [follow this guide to learn how to install it](../plugins/payment/paypal.md).
@@ -316,15 +318,19 @@ Make sure to replace `<YOUR_CLIENT_ID>` with your PayPal client ID. You can retr
 
 If you restart your Next.js backend you should be able to pay with PayPal on checkout.
 
-![Pay with PayPal on Checkout](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003264/Medusa%20Docs/Screenshots/F8OvsOJ_mlx0le.png)
+---
 
-### Customization
+## Development Notes
 
-To customize the pages of the storefront, you can customize the files under the `src/pages` directory.
+### Changing Medusa Backend URL
 
-To customize the components used in the storefront, you can customize the files under the `src/modules` directory.
+By default, the Medusa backend runs at `http://localhost:9000`. This value is defined in your Next.js starter Storefront under the environment variable `NEXT_PUBLIC_MEDUSA_BACKEND_URL`.
 
-To customize the styles of the storefront, you can customize the `src/styles` directory.
+If you need to change the URL of your Medusa backend because you changed the backend's default port or because you deployed your backend, change the value of `NEXT_PUBLIC_MEDUSA_BACKEND_URL` (typically in `.env.local`) to your backend URL. For example:
+
+```bash
+NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9001
+```
 
 ### Change Port
 
@@ -347,25 +353,67 @@ Then, on your backend, update the environment variable `STORE_CORS` to the URL w
 STORE_CORS=http://localhost:<PORT>
 ```
 
-### Development Resources
+### Using Serverless Modules
 
-You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).
+:::note
 
----
+Serverless Modules are currently in beta and, at the moment, they can't be used in the Next.js storefront without the Medusa backend running.
 
-## Storefront Features
+:::
 
-- View all products and manage your cart.
+This starter fully supports the experimental [Product](../experimental/product/overview.mdx) and [Pricing](../experimental/pricing/overview.mdx) modules for retrieving and manipulating product and pricing data directly from a serverless function. This keeps your logic close to the frontend, making it easy to customize or extend Medusa's core functionality from within your Next.js project.
 
-![All Products Page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003278/Medusa%20Docs/Screenshots/1vLAYbH_sulxrr.png)
+By default, this starter uses the standard Medusa API for product, collection, and pricing retrieval.
+
+To enable the usage of the experimental modules, first, set the following environment variables:
+
+- `POSTGRES_URL`: the URL of your PostgreSQL databsae.
+- `NEXT_PUBLIC_BASE_URL`: the URL of your storefront's base URL. For exmaple, if you're running it locally, it should be `http://localhost:8000`.
 
-- Customer authentication and profiles.
+Then, set the following environment variable in both the Next.js storefront and the [Medusa backend](../experimental/index.md#enabling-experimental-features):
 
-![Customer Profile](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003287/Medusa%20Docs/Screenshots/etW3b3L_wccrez.png)
+:::warning
+
+This is a one way process. Once you opt in to these features and update your database, there's no way back. Proceed with caution.
+
+:::
+
+```bash
+MEDUSA_FF_MEDUSA_V2=true
+```
 
-- Full checkout workflow.
+Finally, run migrations in your Medusa backend using the following commands:
 
-![Checkout Page](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003296/Medusa%20Docs/Screenshots/VC8SYfb_eowjno.png)
+```bash
+npx medusa migrations run
+node node_modules/@medusajs/medusa/dist/scripts/migrate-to-pricing-module.js
+```
+
+You can now test it out now. Make sure the Medusa backend is running, then start (or restart) your Next.js storefront:
+
+```bash npm2yarn
+npm run start
+```
+
+If you go to `localhost:8000`, all product and collection data should now be coming from the module. The Product Module routes are all in the `src/app/api` directory for you to customize to your use case.
+
+:::info[Deploying to Vercel]
+
+If you're not planning on using the serverless modules, you might encounter errors when deploying to Vercel. You can safely delete or exclude `the src/app/api` folder before deploying. The API routes are only used by the serverless modules.
+
+:::
+
+### Customization
+
+To customize the pages of the storefront, you can customize the files under the `src/app` directory.
+
+To customize the components used in the storefront, you can customize the files under the `src/modules` directory.
+
+To customize the styles of the storefront, you can customize the `src/styles` directory.
+
+### Development Resources
+
+You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).
 
 ---
 
