Add an Astro Project

The code for this example is available on GitHub:

Example repository/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.

✅ Run Tasks ✅ Cache Task Results ✅ Remote Caching ✅ Explore the Graph ✅ Distribute Task Execution ✅ Integrate with Editors ✅ Automate Updating Nx ✅ Enforce Project Boundaries 🚫 Use Task Executors 🚫 Use Code Generators 🚫 Automate Updating Framework Dependencies

Create an astro app

❯

npm create astro@latest

Add Nx

We can leverage nx init to add Nx to the Astro application.

~/astro-app❯

npx nx@latest init

1 >  NX   🐳 Nx initialization
2
3
4 >  NX   🧑‍🔧 Please answer the following questions about the scripts found in your package.json in order to generate task runner configuration
5
6✔ 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
7
8✔ Does the "build" script create any outputs? If not, leave blank, otherwise provide a path (e.g. dist, lib, build, coverage) · dist
9✔ Enable distributed caching to make your CI faster · No
10
11 >  NX   📦 Installing dependencies
12
13 >  NX   🎉 Done!
14
15   - Enabled computation caching!
16   - Learn more at https://nx.dev/recipes/adopting-nx/adding-to-existing-project.
17

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 or how caching works.

Running Tasks

Because Nx understands package.json scripts, You can run the predefined scripts via Nx.

❯

nx build

If you plan on using your package manager to run the tasks, then you'll want to use nx exec to wrap the command

i.e.

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 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

❯

npm i -DE @nx/js@<nx-version>

Nx 15 and lower use @nrwl/ instead of @nx/

Then generate a project

Directory Flag Behavior Changes

The command below uses the as-provided directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the derived option, omit the --directory flag. See the as-provided vs. derived documentation for more details.

>  NX  Generating @nx/js:library

✔ 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
Nx 15 and lower use @nrwl/ instead of @nx/

If you plan to import .astro files within .ts files, then you can install the @astrojs/ts-plugin.

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

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.

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';