DOCSEARCHbyAlgolia
Submit Docs

Qwik + Astro Integration

repository·build/v2·Indexed 43 days ago

https://github.com/qwikdev/astro

An integration that allows developers to render Qwik components within an Astro project, leveraging Qwik's resumability model for instant interactivity without the need for hydration directives. Includes a starter kit, CLI for project scaffolding, and support for using multiple JSX frameworks side-by-side.

Tokens
16.8K
Snippets
57
Records
90
Agent score
54%

What's inside Qwik Astro

  1. Understand the @QwikDev/astro Starter Kit structure

    build/v2

    The @QwikDev/astro starter kit is designed to integrate Qwik components into Astro projects. The project follows a standard Astro directory structure with specific roles for Qwik and Astro files:

    • public/: Static resources accessible from the site root.
    • src/assets/: Images, SVGs, and other media resources.
    • src/components/: Qwik components (e.g., .tsx files) reside here.
    • src/layouts/: Astro layouts that define the page structure.
    • src/pages/: Astro pages (.astro or .md) that define the application routes.
    • src/styles/: Global CSS files like globals.css.

  2. Understand the @qwik.dev/astro project structure

    build/v2

    The @qwik.dev/astro starter kit organizes files into a standard Astro structure, with specific directories for Qwik components and Astro layouts:

    • public/: Static resources (e.g., favicon.svg) accessible from the site root.
    • src/assets/: Images, SVGs, and other media resources.
    • src/components/: Contains Qwik components (e.g., .tsx files) for reusable UI logic.
    • src/layouts/: Contains Astro layouts that define the structural wrapper for your pages.
    • src/pages/: Contains Astro pages (.astro or .md). Files here are automatically routed based on their filename.
    • src/styles/: Global CSS files (e.g., globals.css).

  3. What is Resumability and JavaScript Streaming?

    build/v2

    Resumability

    Resumability is "Lazy execution". It allows the framework state (like component boundaries) to be built on the server and exist on the client without the client needing to re-execute the framework logic to reach the same state. This avoids the double-execution (server + client) required by traditional hydration.

    JavaScript Streaming

    JavaScript streaming combines Resumability with the ability to stream functions into the browser and buffer them in the cache. The Qwik Optimizer automatically extracts functions and closures into tiny packets, which are then streamed to the browser, optimizing how interactivity is loaded.

  4. Understand JavaScript Streaming

    build/v2

    JavaScript streaming is the combination of Resumability and the ability to stream functions into the browser and buffer them in the cache.

    The Qwik Optimizer automatically extracts functions and closures, streaming them into the browser in small chunks (similar to how video streaming works). This ensures that the JavaScript required for an interaction is only downloaded and executed when needed.

  5. How Qwik and Astro work together (Resumability vs Hydration)

    build/v2

    Unlike traditional frameworks that use partial hydration (requiring directives like client:load or client:only), Qwik uses Resumability.

    In an Astro project, Qwik components are loaded on the server, prefetched, and then "resumed" on the client. This means you do not need hydration directives to make Qwik components interactive. You can simply import and use a Qwik component directly in an .astro file.

    Example: Counter Component

    Qwik Component (src/components/counter.tsx):

    import { component$, useSignal } from "@qwik.dev/core";

export const Counter = component$(() => {
  const counter = useSignal(0);

  return <button onClick$={() => counter.value++}>{counter.value}</button>;
});

    Astro Page (src/pages/index.astro):

    ---
import { Counter } from "../components/counter";
---

<html lang="en">
  <body>
    <h1>Astro.js - Qwik</h1>
    <Counter /> <!-- No client:load directive needed! -->
  </body>
</html>

  6. Understand Qwik's performance model in Astro

    build/v2

    Qwik extends Astro's "Zero JS" principle through Resumability.

    • Complexity: While traditional frameworks increase JavaScript execution linearly $O(n)$ with the number of components, Qwik maintains $O(1)$ constant complexity. The framework runtime is not executed until it is actually needed.
    • Qwikloader: Upon page load, a tiny (~1kb) minified piece of JavaScript called Qwikloader downloads the rest of the application bundles on demand.
    • Fine-grained Lazy Loading: Because Qwik does not need to exhaustively check the render tree during a hydration phase, it can lazy load code at a much more granular level.
    • Speculative Module Fetching: You can achieve instant interactivity in Astro by using Speculative Module Fetching to prefetch application bundles in the background via a service worker.

  9. How Qwik entrypoints are discovered

    build/v2

    The integration uses scanQwikEntrypoints() (located in scan.ts) to automatically identify files that need to be processed by Qwik. It performs a scan using grep to find files containing Qwik imports, specifically looking for:

    • @qwik.dev/core
    • @qwik.dev/react
    • .qwik. patterns

    The scanning process respects include and exclude filter options provided in the configuration.

  10. Communicate between containers using Custom Events

    build/v2

    To share state or communicate between different Qwik containers, use custom events instead of global signals or nano stores.

    Why avoid global signals or nano stores? Using global state in an SSR (Server-Side Rendering) context can lead to shared state across different user requests, causing bugs, memory leaks, and security vulnerabilities.

    Advantages of Custom Events:

    • Performance: Avoids unnecessary state synchronization.
    • Efficiency: Does not wake up the framework on page load.
    • Compatibility: Supports Micro Frontends (MFE) and allows different versions of components to coexist on the same page.
    • Architecture: Promotes an event-driven, decoupled design.

  11. Communicating between Qwik containers using Custom Events

    build/v2

    Because Qwik uses a container-based approach rather than Astro's island architecture, components appear as static data to Astro. This makes sharing state via global signals or libraries like nanostores discouraged in SSR contexts due to potential data isolation bugs and security implications.

    Instead, the recommended way to communicate between different Qwik containers or Astro islands is to use Custom Events. This approach is performant, event-driven, and does not wake up the framework on page load.

  12. How the integration manages the build lifecycle via Astro hooks

    build/v2

    The integration uses two critical Astro hooks to ensure Qwik's client-side requirements are met during the Astro build process:

    • astro:config:setup: Registers the Qwik renderer via addRenderer(). It defines the virtual:qwik-astro virtual module (for runtime render options and the client manifest), resolves source/build paths, and configures qwikVite() with specific file filters and entry points. In build mode, it strips Qwik's client-output hooks so the standalone client build remains authoritative.
    • astro:build:setup: Intercepts the build pipeline to run a separate Qwik client build before Astro's prerender step. It uses scanQwikEntrypoints() to find entry points and runQwikClientBuild() to generate the necessary symbol-to-chunk manifest that the SSR renderer requires.