feat(pie-docs): DSW-000 add nextjs 14 integration guide to docs site (#…

…2063)

* feat(pie-docs): DSW-000 add nextjs 14 integration guide to docs site

* add links to packages

* add test route for new page

* changeset

.changeset/neat-ads-reflect.md

@@ -0,0 +1,5 @@
+---
+"pie-docs": minor
+---
+
+[Added] - NextJS 14 integration guide for web components

apps/pie-docs/src/engineers/web-components/nextjs-14-integration.md

@@ -0,0 +1,84 @@
+---
+eleventyNavigation:
+    key: NextJS 14 Integration
+    parent: engineers-web-components
+    order: 2
+---
+
+## Installation
+Please install the following JET dependencies (examples use `yarn` but feel free to use `npm` if preferred):
+
+```bash
+yarn add @justeattakeaway/pie-css @justeattakeaway/pie-webc @justeattakeaway/pie-icons-webc
+```
+
+And the following third party dependencies:
+```bash
+yarn add @lit-labs/nextjs @lit/react
+```
+
+## Setup
+
+### CSS and Design Token variables
+You should import [@justeattakeaway/pie-css](https://www.npmjs.com/package/@justeattakeaway/pie-css) into your root component file (or wherever you prefer) so that the variables it provides are globally available (some of these variables are used by the component styles):
+
+```js
+// Example - /src/app/layout.tsx
+import '@justeattakeaway/pie-css';
+```
+
+For more information on `pie-css` please take a look at the package [readme](https://github.com/justeattakeaway/pie/tree/main/packages/tools/pie-css)
+
+### Typography
+We have a [dedicated page](/foundations/typography/code/) which explains how to set up typography. In short, you need to install the JET fonts and set up the appropriate `font-face` CSS code.
+
+### NextJS config
+
+We need to update our `next.config.js` file to enable server-side rendering (SSR).
+
+Example minimal config file:
+
+```js
+// Example - ./next.config.js
+const withLitSSR = require('@lit-labs/nextjs')();
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    reactStrictMode: true,
+    swcMinify: true,
+}
+
+module.exports = withLitSSR(nextConfig);
+```
+
+## Usage
+
+{% notification {
+  type: "information",
+  message: "If you are using the app router structure, please ensure you add `\"use client\"` to the top of the files that directly import the PIE components. This does NOT prevent SSR, it just means that PIE components cannot be used directly in React server-components. These client components can then be imported into RSCs."
+} %}
+
+It is recommended to import all components from [@justeattakeaway/pie-webc](https://www.npmjs.com/package/@justeattakeaway/pie-webc). For React-based applications, there is a `/react/` entry point as shown in the example code below:
+
+```jsx
+"use client"
+
+import { PieButton } from "@justeattakeaway/pie-webc/react/button.js";
+import { PieLink } from "@justeattakeaway/pie-webc/react/link.js";
+import { IconCamera } from "@justeattakeaway/pie-icons-webc/dist/react/IconCamera";
+
+export default function SomeComponent() {
+    return (
+        <div>
+            <PieButton size="small-productive" iconPlacement="leading">
+                <IconCamera slot="icon"></IconCamera>
+                Camera Button
+            </PieButton>
+        </div>
+    );
+}
+```
+
+You should now be able to use any components you need in your NextJS application!
+
+Please reach out to us if you have any troubles or spot any errors in our guide.

apps/pie-docs/src/engineers/web-components/overview.md

@@ -8,7 +8,7 @@ permalink: engineers/web-components/
 
 ## Introduction
 
-[Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) are a set of native browser technologies that allow us to build custom components. In other words, create custom HTML elements native to browsers. 
+[Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) are a set of native browser technologies that allow us to build custom components. In other words, create custom HTML elements native to browsers.
 
 Currently, this technology is supported by all browsers, making it possible to have one central library that will work with most frontend frameworks.
 
@@ -36,6 +36,8 @@ For specific framework versions, please follow these guides:
 
 [Vue & Nuxt ‐ Known gotchas](https://github.com/justeattakeaway/pie/wiki/Vue-Nuxt-%E2%80%90-Known-gotchas)
 
+[NextJS 14](/engineers/web-components/nextjs-14-integration/)
+
 For existing users, you may be interested in our [Migration guide of Web Components to Lit 3](https://github.com/justeattakeaway/pie/wiki/PIE-Web-Components-%E2%80%90-Nuxt-2---Next-10---Vue-2-Integration). This guide also details some specific configurations for React, Next and Vue2.
 
 More guides coming soon! 🚀

apps/pie-docs/test/snapshots/expected-routes.snapshot.json

@@ -95,6 +95,7 @@
     "engineers/guidelines",
     "engineers/guidelines/browser-support",
     "engineers/web-components",
+    "engineers/web-components/nextjs-14-integration",
     "foundations",
     "foundations/colour",
     "foundations/colour/tokens/alias/dark",
@@ -134,4 +135,4 @@
     "support",
     "support/contact-us",
     "support/faq"
-]
+]