Navigate function does not work on integrations that do not need a hydration entrypoint

[thejackshelton]

Astro Info

Astro                    v5.1.1
Node                     v18.20.3
System                   Linux (x64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             @qwikdev/astro

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

TLDR:

As an environment agnostic first ui-framework (e.g server, client), Qwik fully supports Astro's client router.

However, the navigate function for the client router does not work when building in the Qwik integration (it does in dev mode). Likely due to pre-existing expectations of hydration.

We have gotten feedback that this is something that should be supported given how it's explained and consumed in a React component in the Astro docs. We can see that it already works in dev mode. QwikDev/astro#40

The error we get when building:

vite]: Rollup failed to resolve import "astro:transitions/client" from "/Users/jackshelton/dev/open-source/qwikdev-astro/apps/demo/src/components/qwik/counter.tsx_Counter_component_Fragment_button_onClick_1_KfE1Zu3VTRY.js".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`
  Stack trace:
    at viteWarn (file:///Users/jackshelton/dev/open-source/qwikdev-astro/node_modules/.pnpm/vite@5.4.11_@types+node@22.10.2/node_modules/vite/dist/node/chunks/dep-CB_7IfJ-.js:65589:17)
    at onRollupWarning (file:///Users/jackshelton/dev/open-source/qwikdev-astro/node_modules/.pnpm/vite@5.4.11_@types+node@22.10.2/node_modules/vite/dist/node/chunks/dep-CB_7IfJ-.js:65619:5)
    at file:///Users/jackshelton/dev/open-source/qwikdev-astro/node_modules/.pnpm/rollup@4.29.1/node_modules/rollup/dist/es/shared/node-entry.js:19537:13
    at ModuleLoader.handleInvalidResolvedId (file:///Users/jackshelton/dev/open-source/qwikdev-astro/node_modules/.pnpm/rollup@4.29.1/node_modules/rollup/dist/es/shared/node-entry.js:20152:26)
 ELIFECYCLE  Command failed with exit code 1.
 ELIFECYCLE  Command failed with exit code 1.

Longer explanation:

Astro integrations that are renderers / frameworks require the addRenderer function.

This function provides a:

• serverEntrypoint
• clientEntrypoint

The client entrypoint is mainly needed for hydration based frameworks. This is also how Astro uses partial hydration to create Astro islands.

In the Qwik integration, we do not need a client entrypoint at all, because there is nothing to hydrate, the server is able to communicate with the client without needing to sync up missing information.

This also means that Qwik components do not need the client directives (e.g client:load, client:visible) etc. to be interactive.

It would appear that somewhere in Astro core, there is a pre-existing expectation that the navigate function is needed with a client hydration entrypoint when building the application.

It may be possible to create a workaround like a virtual module in the Qwik Astro integration, however, I would prefer not to patch core functionality of Astro, and would be happy to help with making sure that people using Astro with Qwik continue to have the same developer experience they know and enjoy.

Happy to pair with someone on this in core.

What's the expected result?

We would expect the functionality to work similar to how it does with the React integration in the docs:

import { component$ } from '@builder.io/qwik';
import { navigate } from 'astro:transitions/client';

export const Navigation = component$(() => {
  return <button onClick$={() => navigate('/test')}>Navigate to test</button>;
});

When building, rollup correctly resolves the Astro client transitions import, and does the same programmatic client rotuer functionality as dev mode in production.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-n2jvyyx5?file=src%2Fpages%2Findex.astro

Participation

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

[ascorbic]

I don't know enough about Qwik's bundling to be sure, but I don't think this is related to any special handling of hydration in Astro, but rather with the way you're handling the client build yourself. When you compile navigate.tsx, you don't have the right plugin to handle the virtual module. In a normal Astro build where clientEntrypoint was provided, it would be compiled as part of the client build, which would include all of the internal Astro plugins.

[ascorbic]

I'm closing this as I don't think this is soemthign that can be fixed on the Astro end. You'll either need to work out a way to compile Qwik as part of the normal astro client build process, or find a different way to handle virtual modules from Astro.

[thejackshelton]

I'll investigate a solution using the clientEntrypoint on our end first.

If that approach isn't feasible, I'll update the documentation to clarify this limitation and close the issue as not planned, likely opening up a new one here.

We want to avoid modifying Astro core functionality as that could lead to maintenance challenges in the future.

[thejackshelton]

I can see that it works without the client entrypoint with this:

import { navigate } from "astro/virtual-modules/transitions-router.js";

Does this narrow anything down @ascorbic ?

I made an empty client.ts after and it doesn't seem to make any difference

export default (element: HTMLElement) =>
  (
    Component: any,
    props: Record<string, unknown>,
    slotted: Record<string, string>,
    options: { client: string }
  ) => {
    // Qwik doesn't need to hydrate, it efficiently has this info already. Slot handling is also done.
    return;
  };

        addRenderer({
          name: "@qwikdev/astro",
          serverEntrypoint: resolver("../server.ts"),
          clientEntrypoint: resolver("../client.ts")
        });

[ascorbic]

Yes, that's because that will resolve without needing the plugin. Adding the client entrypoint isn't the issue: it's the fact that you're compiling code that includes virtual module imports without the Vite plugin to resolve them. Changing those imports to be normal subpath imports means that it will then work.

[thejackshelton]

Yes, that's because that will resolve without needing the plugin. Adding the client entrypoint isn't the issue: it's the fact that you're compiling code that includes virtual module imports without the Vite plugin to resolve them. Changing those imports to be normal subpath imports means that it will then work.

Is this a plugin from Astro core that I can hook into? Or do you think this is something I need to pass into that Qwik client build

[thejackshelton]

I can't seem to find any astro vite plugins that handle this already from the config in the lifecycle hooks. Going to see how to do this in a new vite plugin

[thejackshelton]

        const virtualModulePlugin: PluginOption = {
          name: "virtual-module-resolver",
          enforce: "pre",
          resolveId(id) {
            if (id === "astro:transitions/client") {
              return path.resolve(
                process.cwd(),
                "node_modules",
                "astro",
                "dist",
                "virtual-modules",
                "transitions-router.js"
              );
            }
            return null;
          }
        };

this seems to have done it, but feel like I'm missing a plugin from Astro here 🤔

[thejackshelton]

Figured it out. Astro's build:setup hook provides the current vite state. Appreciate the help Matt!

[ascorbic]

It's probably better to use this.resolve() rather than constructing the path, which may depend on the package manager.