fix: add undocumented options in integrations-reference.mdx

[ArmandPhilippot]

I was looking at the Integrations reference page and noticed some formatting issues... Since Florian is about to give a talk on integrations, I figured it was a good time to do a more thorough check instead! Also, I was worried that you would be bored after 5.2. 😄

Description (required)

Sorry the description isn't really succinct but I'm trying to keep track of the why and when for each point.

In upgrade-to/v5.mx:

• Fixes a mismatch between paths in addDevToolbarApp code snippets (the path is not the same as the one used in the code block's title)

In integrations-reference.mdx:

• Consistent formatting:

  • Updates the Type:/Since block to be consistent with the formatting of API reference
  • Updates the indentation in some code snippets (most of them use 2 spaces)
  • Updates some titles to explicitly show that they are functions (e.g. addMiddleware > addMiddleware())
  • Replaces + with ExpressiveCode notation to highlight added lines in Allow installation with astro add
  • Makes injectRoute and injectTypes consistent with the other options. These were the only objects expanded in the API quick reference, so:
    • it might be better to be consistent with the others
    • since InjectedRoute and InjectedType can be imported, it could be nice to show the types there
    • this reduces the horizontal scroll which might be easier to read on mobile.

• Existing content:

  • Adds the missing refreshContent, middlewareEntryPoint and pages options in Quick API Reference
  • Adds the missing logger option in the type preview of some hooks
  • Adds a link from the Hooks section to the AstroIntegrationLogger since each hook has a logger option
  • Reorders the hooks to match the real order (tested using a custom integration and console.log)
  • Fixes the Previous hook/Next hook links (some was wrong/outdated or the anchor did not match the link)
  • Collects some types into a new section
  • Fixes some types
    • addDevToolbarApp have been updated in the other pages, but not in this one... string was removed in feat(next): TODOs astro#11987)
    • in injectRoute, pattern was displayed twice with a different type (one of them should be prerender)
    • addWatchFile is a function

• New content:

  • Adds the missing buildOutput option in astro:config:done (added in Merge output: hybrid and output: static astro#11824, so v5)
  • Adds the missing toolbar option in astro:server:setup (added in Fix astro/app import astro#7821, so v4.7.0)
  • Adds documentation for astro:build:setup options
  • Adds documentation for astro:build:generated options
  • Adds documentation for astro:build:ssr options
  • Break up IntegrationResolvedRoute and IntegrationRouteData types to avoid too long blocks of code and to make it look more like documentation (see the issue reported by Fryuni on Discord )

Remaining question: the Integrations API page becomes longer than the current Render context page (formerly API reference) we split. Could a section in the sidebar like Runtime API make sense here? Not necessarily now, but the page might get a bit too big for Algolia (~1680 lines, IIRC the former API Reference had a bit more than 2000 lines).

Related issues & labels (optional)

• Suggested label: add new content, consistency/formatting and improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	ba8be88
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/67a4d79377246000086b90ce
😎 Deploy Preview	https://deploy-preview-10822--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/upgrade-to/v5.mdx	Source changed, localizations will be marked as outdated.
en/reference/integrations-reference.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[sarah11918]

Amazing, thank you so much for this initiative Armand!

As you say, in draft so no rush. But would be great for at least @florian-lefebvre and @Fryuni to have a look over when it's ready before I do!

You could also post this in the #integrations channel in Discord to see whether any of our integrations builders are interested in commenting on this!

[ArmandPhilippot]

Oh definitely! There still some work to do here (mainly document what is not documented) so I'll try to do that with my knowledge but yeah, once done a review from our integrations expert would be much appreciated! 😄

[florian-lefebvre]

Feel free to ping me once you're ready!

[ArmandPhilippot]

Oh okay that's why IntegrationResolvedRoute uses entrypoint while we have component in RouteOptions and RouteData.

Actually, I read the description of route option too quickly. We already had a description for component but in the parent section not on its own like prerender, hence the confusion. So I updated that to be consistent.

[florian-lefebvre]

I think this is not always true, eg. for injected routes that reference package exports

[ArmandPhilippot]

You mean when the injected routes comes from node_modules? The path would not be ./node_modules/...?

Reading the JSDoc, it seems a relative path is always the expected format, right? Looking at the hook implementation, I see route.component being used in the logger... But I have no idea what else to expect than a path to a file. 😅

Do you have an example of what this might be (or a direction where I could look)?

[Fryuni]

It is not only that. The reason we renamed to entrypoint in the other hook is exactly because it is not always a component. I can be a TS endpoint, for example.

[ArmandPhilippot]

Yeah I understand that, but I have to admit that I am having a bit of trouble understanding the problem with the description (except that the property name is wrong but it is the name currently in use and we are documenting what currently exists).
But again, I'm not the integration expert here... So maybe some things that seem obvious to you, aren't obvious to me due to a lack of knowledge in this context.

I had tested on my own website where I have both static routes, dynamic routes, endpoints, and injected routes (but which do not refer to node_modules) and in every case, using console.log(route.component), I see:

src/pages/en/index.astro
src/pages/en/[slug].astro
src/pages/feed.xml.ts
src/components/atoms/button/button.stories.astro

(stories.astro are my injected routes if you are wondering)

So it seems to me the description matches what I get. But I haven't tested with an import from a package, so maybe that's the problem...

[florian-lefebvre]

Yeah I was thinking about a package import

[ArmandPhilippot]

So I tried to find an existing package that I could use to test... there is astrojs/web-vitals but it still mentions Astro Studio, so I thought maybe it wasn't the best solution...

I went with a fake package (inspired by a fake fixture in the core repo) and pnpm workspaces:

packages:
  - "fake-packages/*"

Using logger.info(route.component), I see [astro-route-setup] fake-packages/custom-404-pkg/404.astro.
So it's using a relative path, right? However, perhaps because this is a workspace package, it's using the actual path instead of a path from node_modules... But I guess for an installed package, it will be node-modules/fake-packages/....

[florian-lefebvre]

@Fryuni you probably know more about this than me

[Fryuni]

We changed it on routes:resolved, I completely missed the route:setup hook

We should update it on the others and mark the component field as deprecated then. We'll have to carry it for an entire major now 😅

[Fryuni]

Looks great. Left some small notes for us to discuss.

[JusticeMatthew]

Review on talking and docing was great

Also checked for typos and came up empty

Great job 😄