Review of SSR extension to Rollup plugins API

[patak-dev]

Rollup is extending its plugin API to support an isEntry flag in the options of resolveId and resolve. See rollup/rollup#4230

Vite added an ssr boolean flag to resolveId, load, and transform. This doesn't interfere in resolveId as it goes after the options param. But in transform, there isn't an options object:

export function mySSRPlugin() {
  return {
    name: 'my-ssr',
    transform(code, id, ssr) {
      if (ssr) {
        // perform ssr-specific transform...
      }
    }
  }
}

There may be further extensions to the Rollup plugin API (or extensions that originate from Vite). We may want to review the SSR extension before SSR is out of experimental, as IMO the ecosystem of plugins and integrations could still adapt if we do this in a minor. There are probably other API changes to the SSR API anyways and we could bundle these changes together.

See comment from @lukastaegert about their experience in Rollup rollup/rollup#4230 (comment) after using positional args they have switched to only add new things in options, they are suggesting that we switch to

// Nested object
interface Plugin {
  // ...
  resolveId?(
    source: string,
    importer: string | undefined,
    options: { custom?: CustomPluginOptions, vite?: {ssr?: boolean} }
  ): Promise<ResolveIdResult> | ResolveIdResult
}

or

// Nested object
interface Plugin {
  // ...
  resolveId?(
    source: string,
    importer: string | undefined,
    options: { custom?: CustomPluginOptions, viteSsr?: boolean}
  ): Promise<ResolveIdResult> | ResolveIdResult
}

For completeness, we could also just use ssr here, because it is probable that our extensions are also going to be useful to other tools like WMR.

// Nested object
interface Plugin {
  // ...
  resolveId?(
    source: string,
    importer: string | undefined,
    options: { custom?: CustomPluginOptions, ssr?: boolean}
  ): Promise<ResolveIdResult> | ResolveIdResult
}

Bringing the discussion here to avoid derailing the isEntry extension PR.

[lukastaegert]

As I stated in the PR, any of these options would be fine and future proof for Rollup, including the third. That one is probably the best from a dev experience point.

[patak-dev]

We discussed this with the team, and we think we should move forward so the plugin API is future-proof to both rollup and Vite extensions.

Instead of the current ssr boolean positional parameter, resolveId, load and transform will receive an options object with an ssr boolean property:

interface Plugin {
  resolveId?(
    source: string,
    importer: string | undefined,
    options: { custom?: CustomPluginOptions, ssr?: boolean }
  ): ...

  load?(
    id: string,
    options?: { ssr?: boolean }
  ): ...

  transform?(
    code: string,
    id: string,
    options?: { ssr?: boolean }
  ): ...
}

Rollup already has an options object in resolveId, so in that case we are just adding the ssr boolean to it. For load and transform, we'll add the options object even if there isn't one in rollup's API. Later rollup may also need it as an extension point as @lukastaegert suggested.

This is a breaking change, but we believe that it is worth doing now that we can still coordinate between the different frameworks. @antfu @benmccann @brillout @frandiox @galvez @DylanPiercey @ryansolid @natemoo-re @fks @drwpow (please help us to involve others that may be affected by this), what do you think? We could target 2.7 or 2.8 if we need more time (but probably better to do it sooner rather than later)

[benmccann]

This sounds like an easy change to make on the Svelte side. CC @dominikg

[dominikg]

Yes, we should add that to vite-plugin-svelte before vite releases this change so users updating vite won't encounter it breaking.

Tracking in sveltejs/vite-plugin-svelte#186

[ryansolid]

Yeah this all sounds good to me. We can get the temporary patch in pretty quick for Solid.

[patak-dev]

Great, thanks for checking this out so quickly. Adding @jplhomer and @marvinhagemeister also to the discussion

[jplhomer]

Thanks for the heads-up @patak-js. We'll apply a patch for this in Hydrogen this week.

[brillout]

👍

FYI, newly released [email protected] that is ready for the breaking change (vikejs/vike@8312b5d).

// https://github.com/vitejs/vite/discussions/5109#discussioncomment-1450726
function isSSR(options: undefined | boolean | { ssr: boolean }): boolean {
  if (options === undefined) {
    return false
  }
  if (typeof options === 'boolean') {
    return options
  }
  if (isObject(options)) {
    return !!options.ssr
  }
  assert(false)
}

[dominikg]

released @sveltejs/[email protected] with support for this sveltejs/vite-plugin-svelte#187

thanks for driving this @patak-js

[frandiox]

Thanks @patak-js ! I think this won't be a breaking change for vitedge or vite-ssr, so we're good 👍

[galvez]

Thanks for the heads up — FWIW I don't use any of these features yet in fastify-vite though. I might start using them soon to provide virtual modules for common boilerplate items.

[patak-dev]

We have now a PR to update the plugin hooks in #5253. It currently implements what we have discussed. Moving a discussion about server.pluginContainer from the PR here to get feedback.

Vite also exposes in the JS API through the server, access to the pluginContainer so users can externally call resolveId, transform and load.
The current interface is

export interface PluginContainer {
  options: InputOptions
  buildStart(options: InputOptions): Promise<void>
  resolveId(
    id: string,
    importer?: string,
    skip?: Set<Plugin>,
    ssr?: boolean
  ): Promise<PartialResolvedId | null>
  transform(
    code: string,
    id: string,
    inMap?: SourceDescription['map'],
    ssr?: boolean
  ): Promise<SourceDescription | null>
  load(id: string, ssr?: boolean): Promise<LoadResult | null>
  close(): Promise<void>
}

We didn't discuss changing this API yet. I don't know how many plugins or integrations are using it. Contrary to the changes in the plugin hooks, modifying this one can not be done in a compatible way (where plugin authors can check if the ssr param is a boolean for transform and load).
I think the API could be changed to

export interface PluginContainer {
  options: InputOptions
  buildStart(options: InputOptions): Promise<void>
  resolveId(
    id: string,
    importer?: string,
    options?: { skip?: Set<Plugin>, ssr?: boolean }
  ): Promise<PartialResolvedId | null>
  transform(
    code: string,
    id: string,
    options?: { inMap?: SourceDescription['map'], ssr?: boolean }
  ): Promise<SourceDescription | null>
  load(
    id: string, 
    options?: { ssr?: boolean }
  ): Promise<LoadResult | null>
  close(): Promise<void>
}

I don't know if this change is justified though. This isn't an API shared with Rollup. And this wouldn't only affect the experimental SSR API (it also touches skip and inMap, but these have probably even less usage). Is there someone using server.pluginContainer out of Vite Core? Thoughts?

[patak-dev]

Send #5294 to move this forward, most plugins and framework authors confirmed already that they aren't even using server.pluginContainer