[AnalogJS v3] RFC: Nitro-style Vite plugin interop hooks for Analog compilation

[benpsnyder]

Summary

The stylesheet pipeline work exposed a broader architectural question: how should Analog let external Vite plugins participate in framework compilation without turning @analogjs/vite-plugin-angular into the owner of Analog-specific policy or a broad new plugin surface?

Based on review feedback, the direction should be:

• keep @analogjs/vite-plugin-angular very thin and focused on Angular compilation/resource integration
• avoid new packages for this work
• avoid introducing a broad public API that makes this feel like a custom Analog plugin system
• prefer a model closer to Nitro v3, where ordinary Vite plugins can expose a framework-specific setup hook that the framework picks up and wires into compilation

Research reference:

• Nitro discussion: Interoperability between Nitro modules and Vite plugins nitrojs/nitro#3680

Problem

Right now, features like stylesheet preprocessing need a seam that plain Vite plugins cannot fully reach on their own because part of the work happens inside Angular compilation/resource loading.

At the same time, we do not want to solve that by:

• growing @analogjs/vite-plugin-angular into a general Analog extension host
• introducing new shared packages for one feature
• inventing a parallel "Analog plugin" ecosystem when normal Vite plugins should remain the primary authoring model

We need a way for Analog compilation to be interoperable with Vite plugins while keeping framework ownership and compiler ownership separated.

Proposed Direction

Use a Nitro-like model:

• contrib authors still write normal Vite plugins
• a Vite plugin can optionally expose an analog setup hook
• Analog discovers those plugins during setup and calls that hook with a narrow framework integration context
• @analogjs/vite-plugin-angular only consumes the registrations/integration points it needs for Angular compilation

High-level sketch:

import type { Plugin } from 'vite';

export interface AnalogPluginContext {
  registerStylePreprocessor(preprocessor: StylePreprocessor): void;
}

export type AnalogInteropPlugin = Plugin & {
  analog?: {
    setup?(ctx: AnalogPluginContext): void | Promise<void>;
  };
};

The important part is not the exact shape of the API. The important part is the boundary:

• Vite plugin remains the public extension unit
• Analog owns only the minimal setup context needed for framework interop
• Angular compilation stays behind a thin seam in @analogjs/vite-plugin-angular

Initial Scope

The first implementation should stay narrow and solve the current stylesheet case only.

That likely means:

• @analogjs/platform owns discovery of plugin.analog?.setup(...)
• @analogjs/platform owns the broader style-pipeline authoring/config surface
• @analogjs/vite-plugin-angular keeps only:
  • stylesheet preprocessor integration into Angular compilation
  • registry/compiler-host integration
  • minimal wiring needed to apply registered transforms
• no new packages
• no generic helper surface exported from @analogjs/vite-plugin-angular

Why This Direction

This keeps the package boundaries aligned with maintainer feedback:

• Analog policy stays out of @analogjs/vite-plugin-angular
• contrib authors can integrate through normal Vite plugins instead of a bespoke Analog plugin format
• framework-specific seams still exist where Vite alone cannot reach Angular compilation internals

It also gives us a path for other future integrations, but without committing to a generalized plugin framework up front.

Open Questions

• Where should plugin discovery live: entirely in @analogjs/platform, or split between platform and lower-level integrations?
• What is the smallest useful analog.setup context for the stylesheet case?
• How should setup ordering interact with normal Vite plugin ordering?
• How should this behave in dev/HMR when Angular compilation paths do not always provide full stylesheet context?
• What is the right compatibility story for Vite 6-8?
• Which future use cases actually justify expanding the setup context beyond styles?

Acceptance Criteria

• document a Nitro-inspired interop model that uses normal Vite plugins as the extension unit
• identify the minimal framework-owned setup context needed for stylesheet preprocessing
• define a package boundary where @analogjs/vite-plugin-angular remains compiler-focused and thin
• avoid new packages as part of this direction
• identify what work should stay in the current PR versus what should land as follow-up

[brandonroberts]

Resolved Design Decisions

Plugin discovery lives in vite-plugin-angular

Discovery happens in vite-plugin-angular's buildStart hook, scanning resolvedConfig.plugins for plugin.analog?.setup. This keeps vite-plugin-angular standalone (no dependency on platform), and ensures the interop works for anyone using vite-plugin-angular directly without platform.

Smallest useful analog.setup context

export type StylePreprocessor = (code: string, filename: string) => string | Promise<string>;

export interface AnalogPluginContext {
  registerStylePreprocessor(preprocessor: StylePreprocessor): void;
}

export type AnalogIntegrationPlugin = Plugin & {
  analog?: {
    setup?(ctx: AnalogPluginContext): void | Promise<void>;
  };
};

Registered preprocessors run before Vite's preprocessCSS — they are pre-transforms. Vite's Sass/Less/PostCSS pipeline stays authoritative. The gap this fills is that external tools need to touch stylesheet content before it enters that pipeline, since Angular compilation inlines it before Vite sees it.

Types are exported from @analogjs/vite-plugin-angular for DX but are not required — discovery is structural (plugin.analog?.setup), not type-gated.

Setup ordering follows Vite plugin order

Multiple registered preprocessors compose as a pipeline, ordered by their position in resolvedConfig.plugins (which respects enforce: 'pre' / default / enforce: 'post'). No separate priority system.

input → preprocessor1 → preprocessor2 → preprocessCSS → output

Dev/HMR: same pipeline across all compilation paths

The composed styleTransform applies to all three stylesheet paths — ngtsc (augmentHostWithResources), Angular Compilation API (transformStylesheet callback), and JIT (virtual style modules). No behavioral divergence between modes.

All three callsites are already async, so the async preprocessor signature is a drop-in.

Error handling

Preprocessor failures are wrapped with the originating plugin name before rethrowing:

[analog] Style preprocessor from plugin "vite-plugin-xyz" failed for "app.component.scss": <original error>

Vite 6-8 compatibility

No risk. The surface area is resolvedConfig.plugins, buildStart, and configResolved — stable Vite APIs unchanged across major versions.

Future expansion

The analog namespace object and AnalogPluginContext give room to add registration methods (template transforms, build hooks, etc.) without breaking changes. The context should only grow when a concrete use case demands it — no speculative API surface.

Initial scope

• AnalogIntegrationPlugin type with analog.setup(ctx)
• AnalogPluginContext with registerStylePreprocessor only
• Discovery in buildStart
• Composed pipeline for AOT, Angular Compilation API, and JIT paths
• Error wrapping naming the failing plugin
• Types exported from @analogjs/vite-plugin-angular
• No new packages