Support for Starlight in an Nx monorepo style setting

[bjornharvold]

What version of starlight are you using?

0.25.x

What is your idea?

Currently, starlight does not work when not in root. General discussion about this has been happening here: nxtensions/nxtensions#33.

Is there a configuration starlight could expose that would allow it to run under ./apps/astro-app instead of root?

Why is this feature necessary?

Nx supports Astro but the next level of support needs to come from theme creators.

Put them all together in a monorepo, you theme can be the playground for which to embed any type of dynamic component using Islands. Theme creator would get access to enterprise customers who mostly use monorepos and want their code all in one place.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[HiDeoo]

Thanks for your feedback 🙌

Currently, starlight does not work when not in root.

I haven't used Nx in a very long time so this may be a dumb question, but could you elaborate on this? What do you mean by "starlight does not work when not in root", what is the exact issue?

Starlight itself is used for its own documentation which lives in docs/ directory in this monorepo, this project uses Starlight for its documentation in a docs/ directory in its own monorepo, and there is quite a few other examples of Starlight being used in monorepos. Is there something specific to Nx that makes it not work in this case?

As far as I can imagine, the only difference when installing Starlight in an existing monorepo is that you would skip the git inizialization step (as you're already in a git repository) when running npm create astro@latest -- --template starlight or use the --no-git option.

Again, I may be missing something, so please let me know if there is something specific to Nx that makes it not work in this case.

[bjornharvold]

Hi @HiDeoo

Guessing it has something to do with paths.

I am running nx dev docs monorepo-typescript directory (2 levels up).

[delucis]

Ah, I’ve seen this error before but I’m trying to remember exactly the cause. Could you share your docs/src/content/config.ts?

[bjornharvold]

Hi @delucis

Here you go. Copied directly from your examples directory:

import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
	docs: defineCollection({ schema: docsSchema() }),
};

[delucis]

Thanks! Really puzzled why you’re seeing that error 🤔

The line that is throwing according to the error overlay is this one:

starlight/packages/starlight/utils/navigation.ts

Line 224 in c75bd42

.filter((doc) => !doc.entry.data.sidebar.hidden)

So somehow the sidebar property is undefined, but the docsSchema() should ensure it never is, so something weird is happening, like maybe Astro not finding src/content/config.ts for some reason?

[HiDeoo]

I just tried setting up a repro using Nx and the @nxtensions/astro linked above but for me, everything works fine so I'm starting to think this may not be related to Nx.

like maybe Astro not finding src/content/config.ts for some reason?

I'm thinking the same, one of the only way for me to reproduce this exact issue is for example renaming src/content/config.ts to src/content/config.ts (notice the space at the end) and then running the project.

Would you be able to share the project you're seeing this issue with @bjornharvold ?

[bjornharvold]

Hi both,

Here is a repo that was taken from a larger repo with everything removed except the Astro app:

https://github.com/bjornharvold/nx-starlight

[HiDeoo]

Thanks for sharing your repro.

It looks like the issue is related to @analogjs/astro-angular and commenting out this Astro integration in your apps/docs/astro.config.mjs file resolves the issue.

If I'm not wrong, it looks like the issue may be in the @analogjs/vite-plugin-angular Vite plugin that is added by this integration, altho personally I have never used this plugin nor have an idea about what it does.

If I am correct, this integration adds supports for rendering Angular component, is this something you plan on using in your Starlight documentation?

[delucis]

The Angular Three docs might be a helpful reference. They also render Angular components (see https://angularthree.netlify.app/core/getting-started/first-scene/ for example) using the Analog integration and their repo looks to be an Nx monorepo.

Repo: https://github.com/angular-threejs/angular-three
Docs config: https://github.com/angular-threejs/angular-three/blob/main/apps/astro-docs/astro.config.mjs

[brandonroberts]

Thanks for taking a look Astro team! There was a missing file that wasn't included tsconfig.app.json from the docs. Angular Compilation needs a TypeScript configuration file, or else it emits empty JavaScript output. it doesn't support native single file compilation yet also.

https://analogjs.org/docs/packages/astro-angular/overview#setting-up-the-typescript-config

I made a PR against the repository that shows it working

bjornharvold/nx-starlight#1

[delucis]

Amazing — thanks for sharing @brandonroberts 💖

[bjornharvold]

Thank you

Yes we are 💯 Angular on the Front-End and wanted to use Astro Islands to render some of our components in our documentation.

Will have a look at Angular Three. If it gets the job done, I'm a happy camper!

🍻