From a938db178044774ff51efec6132c50508efed5fd Mon Sep 17 00:00:00 2001 From: Jamie Maguire Date: Fri, 15 Nov 2024 13:07:40 +0000 Subject: [PATCH] feat(pie-docs): DSW-000 add nuxt 3 integration guide to docs (#2066) * feat(pie-docs): DSW-000 add nuxt 3 integration guide to docs * add test route for new page * update overview page --- .changeset/slimy-socks-switch.md | 5 + .../nextjs-14.md} | 10 +- .../integration-guides/nuxt-3.md | 133 ++++++++++++++++++ .../src/engineers/web-components/overview.md | 12 +- .../snapshots/expected-routes.snapshot.json | 3 +- yarn.lock | 6 +- 6 files changed, 158 insertions(+), 11 deletions(-) create mode 100644 .changeset/slimy-socks-switch.md rename apps/pie-docs/src/engineers/web-components/{nextjs-14-integration.md => integration-guides/nextjs-14.md} (92%) create mode 100644 apps/pie-docs/src/engineers/web-components/integration-guides/nuxt-3.md diff --git a/.changeset/slimy-socks-switch.md b/.changeset/slimy-socks-switch.md new file mode 100644 index 0000000000..e55d2cb211 --- /dev/null +++ b/.changeset/slimy-socks-switch.md @@ -0,0 +1,5 @@ +--- +"pie-docs": minor +--- + +[Added] - Nuxt3 integration guide to docs site diff --git a/apps/pie-docs/src/engineers/web-components/nextjs-14-integration.md b/apps/pie-docs/src/engineers/web-components/integration-guides/nextjs-14.md similarity index 92% rename from apps/pie-docs/src/engineers/web-components/nextjs-14-integration.md rename to apps/pie-docs/src/engineers/web-components/integration-guides/nextjs-14.md index ccc295523c..7904cc1aa6 100644 --- a/apps/pie-docs/src/engineers/web-components/nextjs-14-integration.md +++ b/apps/pie-docs/src/engineers/web-components/integration-guides/nextjs-14.md @@ -2,7 +2,7 @@ eleventyNavigation: key: NextJS 14 Integration parent: engineers-web-components - order: 2 + order: 3 --- ## Installation @@ -16,6 +16,7 @@ And the following third party dependencies: ```bash yarn add @lit-labs/nextjs @lit/react ``` +--- ## Setup @@ -51,6 +52,8 @@ const nextConfig = { module.exports = withLitSSR(nextConfig); ``` +--- + ## Usage {% notification { @@ -79,6 +82,11 @@ export default function SomeComponent() { } ``` +{% notification { + type: "information", + message: "Check individual component `code` pages on this website to see how to use them specifically in your application. Such as [PIE Button](/components/button/code/)." +} %} + 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. diff --git a/apps/pie-docs/src/engineers/web-components/integration-guides/nuxt-3.md b/apps/pie-docs/src/engineers/web-components/integration-guides/nuxt-3.md new file mode 100644 index 0000000000..70fa8f6ca2 --- /dev/null +++ b/apps/pie-docs/src/engineers/web-components/integration-guides/nuxt-3.md @@ -0,0 +1,133 @@ +--- +eleventyNavigation: + key: Nuxt 3 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 nuxt-ssr-lit +``` + +## Setup + +### CSS and Design Token variables +You should add [@justeattakeaway/pie-css](https://www.npmjs.com/package/@justeattakeaway/pie-css) into your Nuxt config 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 Nuxt Config - most of the properties removed for demonstration. +export default defineNuxtConfig({ + css: ['@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. + +### Nuxt config + +To get our components working, ensure you are applying the following rules to your `nuxt.config.ts` file: + +```ts +export default defineNuxtConfig({ + ssr: true, + + nitro: { + moduleSideEffects: [ + '@justeattakeaway/pie-icons-webc', + '@justeattakeaway/pie-webc', + ], + }, + + modules: [['nuxt-ssr-lit', { litElementPrefix: ['pie-', 'icon-'] }]], + + imports: { + transform: { + exclude: [/\bpie-\b/, /\bicon-\b/], + }, + }, + + css: ['@justeattakeaway/pie-css'], + devtools: { enabled: true }, + + devServer: { + port: 3002, + }, + + compatibilityDate: '2024-07-23', +}); +``` +### Nuxt Configuration Breakdown + +#### 1. **Server-Side Rendering** +- **`ssr: true`** + Enables **Server-Side Rendering (SSR)** for improved SEO and faster initial page loads by rendering pages on the server. + +#### 2. **Nitro Configuration** +- **`moduleSideEffects`** + Includes the following modules during the build to ensure side effects like custom element registration: + - `@justeattakeaway/pie-icons-webc` + - `@justeattakeaway/pie-webc` + +#### 3. **Modules** +- Adds the **`nuxt-ssr-lit`** module to enable SSR compatibility for Lit web components. +- **`litElementPrefix`** specifies the prefixes for custom elements to be treated as Lit elements: + - `pie-` + - `icon-` + +#### 4. **Imports** +- **`imports.transform.exclude`** + Prevents Nuxt from automatically transforming imports matching these patterns: + - `pie-` + - `icon-` + +#### 5. **Global CSS** +- Includes global styles from the `@justeattakeaway/pie-css` package for styling custom components. + +#### 6. **Compatibility Date** +- **`compatibilityDate: '2024-07-23'`** + Ensures behaviour aligns with Nuxt's functionality as of the specified date, preventing breaking changes introduced after this date. + +--- + +## Usage + +It is recommended to import all components from [@justeattakeaway/pie-webc](https://www.npmjs.com/package/@justeattakeaway/pie-webc). + +In your components, you should be able to render components like so: + +```html + + + +``` + +{% notification { + type: "information", + message: "Check individual component \`code\` pages on this website to see how to use them specifically in your application. Such as [PIE Button](/components/button/code/)." +} %} + +You should now be able to use any components you need in your Nuxt application! + +Please reach out to us if you have any troubles or spot any errors in our guide. diff --git a/apps/pie-docs/src/engineers/web-components/overview.md b/apps/pie-docs/src/engineers/web-components/overview.md index 39d79195b7..d8e9bb0c1a 100644 --- a/apps/pie-docs/src/engineers/web-components/overview.md +++ b/apps/pie-docs/src/engineers/web-components/overview.md @@ -28,15 +28,15 @@ ___ For every framework, you can start with our [Prerequisites Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components). -For specific framework versions, please follow these guides: +### Integration Guides +For integrating our components with specific frameworks, please follow these guides: -[Vue 3 Integration Guide](https://github.com/justeattakeaway/pie/wiki/PIE-Web-Components-%E2%80%90-Vue-Integration-Guide) +- [Nuxt 3](/engineers/web-components/integration-guides/nuxt-3/) -[Nuxt 3 Integration Guide](https://github.com/justeattakeaway/pie/wiki/PIE-Web-Components-%E2%80%90-Nuxt-3) +- [NextJS 14](/engineers/web-components/integration-guides/nextjs-14/) -[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/) +### Other guides +- [Vue & Nuxt ‐ Known gotchas](https://github.com/justeattakeaway/pie/wiki/Vue-Nuxt-%E2%80%90-Known-gotchas) 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. diff --git a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json index 023d4fd076..3e7b46be8e 100644 --- a/apps/pie-docs/test/snapshots/expected-routes.snapshot.json +++ b/apps/pie-docs/test/snapshots/expected-routes.snapshot.json @@ -96,7 +96,8 @@ "engineers/guidelines", "engineers/guidelines/browser-support", "engineers/web-components", - "engineers/web-components/nextjs-14-integration", + "engineers/web-components/integration-guides/nextjs-14", + "engineers/web-components/integration-guides/nuxt-3", "foundations", "foundations/colour", "foundations/colour/tokens/alias/dark", diff --git a/yarn.lock b/yarn.lock index 34b1e9d2df..8f13837864 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5063,7 +5063,7 @@ __metadata: languageName: unknown linkType: soft -"@justeattakeaway/pie-monorepo-utils@0.0.0, @justeattakeaway/pie-monorepo-utils@workspace:packages/tools/pie-monorepo-utils": +"@justeattakeaway/pie-monorepo-utils@0.1.0, @justeattakeaway/pie-monorepo-utils@workspace:packages/tools/pie-monorepo-utils": version: 0.0.0-use.local resolution: "@justeattakeaway/pie-monorepo-utils@workspace:packages/tools/pie-monorepo-utils" languageName: unknown @@ -23030,7 +23030,7 @@ __metadata: "@justeattakeaway/browserslist-config-pie": 0.2.0 "@justeattakeaway/pie-css": 0.13.1 "@justeattakeaway/pie-icons": 5.2.0 - "@justeattakeaway/pie-monorepo-utils": 0.0.0 + "@justeattakeaway/pie-monorepo-utils": 0.1.0 "@types/markdown-it": 13.0.2 eleventy-plugin-rev: 1.1.1 eleventy-plugin-toc: 1.1.5 @@ -23136,7 +23136,7 @@ __metadata: "@justeattakeaway/pie-link": 1.0.0 "@justeattakeaway/pie-lottie-player": 0.0.5 "@justeattakeaway/pie-modal": 1.0.0 - "@justeattakeaway/pie-monorepo-utils": 0.0.0 + "@justeattakeaway/pie-monorepo-utils": 0.1.0 "@justeattakeaway/pie-notification": 0.12.6 "@justeattakeaway/pie-radio": 0.5.0 "@justeattakeaway/pie-radio-group": 0.3.0