From 4a7099e3430e7c93c319e65836d04c61759c6c85 Mon Sep 17 00:00:00 2001 From: Caleb Ukle Date: Mon, 24 Jul 2023 11:42:53 -0500 Subject: [PATCH] docs(core): add astro recipe --- docs/generated/manifests/menus.json | 24 ++++ docs/generated/manifests/nx.json | 30 +++++ docs/map.json | 6 + docs/shared/recipes/add-stack/add-astro.md | 149 +++++++++++++++++++++ docs/shared/reference/sitemap.md | 1 + 5 files changed, 210 insertions(+) create mode 100644 docs/shared/recipes/add-stack/add-astro.md diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 34a383b4bf76a..f5e5156d7da95 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -3599,6 +3599,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Add an Astro Project", + "path": "/showcase/example-repos/add-astro", + "id": "add-astro", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Powering Up React Development With Nx", "path": "/showcase/example-repos/react-nx", @@ -3715,6 +3723,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Add an Astro Project", + "path": "/showcase/example-repos/add-astro", + "id": "add-astro", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Powering Up React Development With Nx", "path": "/showcase/example-repos/react-nx", @@ -3822,6 +3838,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Add an Astro Project", + "path": "/showcase/example-repos/add-astro", + "id": "add-astro", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Powering Up React Development With Nx", "path": "/showcase/example-repos/react-nx", diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 605a919fac732..9e66d3671c7ac 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -4487,6 +4487,16 @@ "path": "/showcase/example-repos/add-qwik", "tags": [] }, + { + "id": "add-astro", + "name": "Add an Astro Project", + "description": "Add Nx to an Astro project", + "file": "shared/recipes/add-stack/add-astro", + "itemList": [], + "isExternal": false, + "path": "/showcase/example-repos/add-astro", + "tags": [] + }, { "id": "react-nx", "name": "Powering Up React Development With Nx", @@ -4633,6 +4643,16 @@ "path": "/showcase/example-repos/add-qwik", "tags": [] }, + { + "id": "add-astro", + "name": "Add an Astro Project", + "description": "Add Nx to an Astro project", + "file": "shared/recipes/add-stack/add-astro", + "itemList": [], + "isExternal": false, + "path": "/showcase/example-repos/add-astro", + "tags": [] + }, { "id": "react-nx", "name": "Powering Up React Development With Nx", @@ -4768,6 +4788,16 @@ "path": "/showcase/example-repos/add-qwik", "tags": [] }, + "/showcase/example-repos/add-astro": { + "id": "add-astro", + "name": "Add an Astro Project", + "description": "Add Nx to an Astro project", + "file": "shared/recipes/add-stack/add-astro", + "itemList": [], + "isExternal": false, + "path": "/showcase/example-repos/add-astro", + "tags": [] + }, "/showcase/example-repos/react-nx": { "id": "react-nx", "name": "Powering Up React Development With Nx", diff --git a/docs/map.json b/docs/map.json index 33efc85103dfa..3a85a21b80ae7 100644 --- a/docs/map.json +++ b/docs/map.json @@ -1040,6 +1040,12 @@ "description": "Add a Qwik project to your repo", "file": "shared/recipes/add-stack/add-qwik" }, + { + "name": "Add an Astro Project", + "id": "add-astro", + "description": "Add Nx to an Astro project", + "file": "shared/recipes/add-stack/add-astro" + }, { "name": "Powering Up React Development With Nx", "id": "react-nx", diff --git a/docs/shared/recipes/add-stack/add-astro.md b/docs/shared/recipes/add-stack/add-astro.md new file mode 100644 index 0000000000000..a2212a4e9b95a --- /dev/null +++ b/docs/shared/recipes/add-stack/add-astro.md @@ -0,0 +1,149 @@ +# Add an Astro Project + +The code for this example is available on GitHub: + +{% github-repository url="https://github.com/nrwl/nx-recipes/tree/main/astro-standalone" /%} + +**Supported Features** + +Because we are not using an Nx plugin for Astro, there are few items we'll have to configure manually. We'll have to configure our own build system. There are no pre-created Astro-specific code generators. And we'll have to take care of updating any framework dependencies as needed. + +{% pill url="/core-features/run-tasks" %}✅ Run Tasks{% /pill %} +{% pill url="/core-features/cache-task-results" %}✅ Cache Task Results{% /pill %} +{% pill url="/core-features/share-your-cache" %}✅ Share Your Cache{% /pill %} +{% pill url="/core-features/explore-graph" %}✅ Explore the Graph{% /pill %} +{% pill url="/core-features/distribute-task-execution" %}✅ Distribute Task Execution{% /pill %} +{% pill url="/core-features/integrate-with-editors" %}✅ Integrate with Editors{% /pill %} +{% pill url="/core-features/automate-updating-dependencies" %}✅ Automate Updating Nx{% /pill %} +{% pill url="/core-features/enforce-project-boundaries" %}✅ Enforce Project Boundaries{% /pill %} +{% pill url="/core-features/plugin-features/use-task-executors" %}🚫 Use Task Executors{% /pill %} +{% pill url="/core-features/plugin-features/use-code-generators" %}🚫 Use Code Generators{% /pill %} +{% pill url="/core-features/automate-updating-dependencies" %}🚫 Automate Updating Framework Dependencies{% /pill %} + +## Create an astro app + +```shell +npm create astro@latest +``` + +## Add Nx + +We can leverage [`nx init`](/recipes/adopting-nx/adding-to-existing-project#installing-nx-on-a-non-monorepo-project) to add Nx to the Astro application. + +```{% command="npx nx@latest init" path="~/astro-app"%} + > NX 🐳 Nx initialization + + + > NX 🧑‍🔧 Please answer the following questions about the scripts found in your package.json in order to generate task runner configuration + +✔ Which of the following scripts are cacheable? (Produce the same output given the same input, e.g. build, test and lint usually are, serve and start are not). You can use spacebar to select one or more scripts. · build + +✔ Does the "build" script create any outputs? If not, leave blank, otherwise provide a path (e.g. dist, lib, build, coverage) · dist +✔ Enable distributed caching to make your CI faster · No + + > NX 📦 Installing dependencies + + > NX 🎉 Done! + + - Enabled computation caching! + - Learn more at https://nx.dev/recipes/adopting-nx/adding-to-existing-project. +``` + +You can add a task as cacheable after the fact by updating the `cacheableOperations` in the `nx.json` file. Learn more about [caching task results](/recipes/adopting-nx/adding-to-existing-project#installing-nx-on-a-non-monorepo-project) or [how caching works](https://nx.dev/core-features/cache-task-results). + +## Running Tasks + +Because Nx [understands package.json scripts](/reference/project-configuration#project-configuration), You can run the predefined scripts via Nx. + +```shell +nx build +``` + +If you plan on using your package manager to run the tasks, then you'll want to use [`nx exec`](/packages/nx/documents/exec) to wrap the command + +i.e. + +```json {% fileName="package.json" %} +{ + "scripts": { + "e2e": "nx exec -- playwright test" + } +} +``` + +Now when running `npm run e2e` Nx will be able to check if there is a cache hit or not. + +If you plan to only run tasks with the Nx CLI, then you can omit `nx exec`. The safest way is to always include it in the package.json script. + +## Using Other Plugins + +With Nx plugins, you can create projects to help break out functionality of the project. For example, using the [`@nx/js:library`](https://nx.dev/packages/js/generators/library#@nx/js:library) to contain our reusable `.astro` components. + +Install `@nx/js` plugin. + +> Note: you should make sure any first party, `@nx/` scoped, plugins match the `nx` package version + +```shell +npm i -DE @nx/js@ +``` + +Then generate a project + +```{% command="nx g lib --simpleName --minimal} +> NX Generating @nx/js:library + +✔ What name would you like to use for the library? · ui +✔ Which unit test runner would you like to use? · none +✔ Which bundler would you like to use to build the library? Choose 'none' to skip build setup. · none + +CREATE ui/tsconfig.json +CREATE ui/src/index.ts +CREATE ui/src/lib/ui.ts +CREATE ui/tsconfig.lib.json +CREATE ui/project.json +CREATE ui/.eslintrc.json +UPDATE tsconfig.json +``` + +If you plan to import `.astro` files within `.ts` files, then you can install the [`@astrojs/ts-plugin`](https://www.npmjs.com/package/@astrojs/ts-plugin). + +```json {% fileName="tsconfig.json" %} +{ + "extends": "astro/tsconfigs/strict", + "compilerOptions": { + "baseUrl": ".", + "plugins": [ + { + "name": "@astrojs/ts-plugin" + } + ], + "paths": { + "@myrepo/ui": ["ui/src/index.ts"] + } + } +} +``` + +An easier option is to allow importing the files directly instead of reexporting the `.astro` files via the `index.ts`. +You can do this by allowing deep imports in the tsconfig paths + +```json {% fileName="tsconfig.json" %} +{ + "extends": "astro/tsconfigs/strict", + "compilerOptions": { + "baseUrl": ".", + "paths": { + // Note: the * allowing the deep imports + "@myrepo/ui/*": ["ui/src/*"] + } + } +} +``` + +This allows imports in our `.astro` files from other projects like so. + +```ts {% fileName="src/pages/index.astro" %} +import Card from '@myrepo/ui/Card.astro'; +import Footer from '@myrepo/ui/Footer.astro'; +import Header from '@myrepo/ui/Header.astro'; +``` diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 7d8cb73e7d885..1f5cb3f3a1d48 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -178,6 +178,7 @@ - [Add a Lit Project](/showcase/example-repos/add-lit) - [Add a Solid Project](/showcase/example-repos/add-solid) - [Add a Qwik Project](/showcase/example-repos/add-qwik) + - [Add an Astro Project](/showcase/example-repos/add-astro) - [Powering Up React Development With Nx](/showcase/example-repos/react-nx) - [Using Apollo GraphQL](/showcase/example-repos/apollo-react) - [Using Prisma with NestJS](/showcase/example-repos/nestjs-prisma)