feat: add `@netlify/vite-plugin-tanstack-start` #455

serhalp · 2025-09-17T18:51:49Z

Summary

This adds a framework-agnostic Vite build plugin that prepares a Vite app for deployment to Netlify. It expects that the Vite app has an ssr environment (and no other server environments to deploy) that has exactly one bundle entry and that this entry is a server request entry point—a module with a default export containing a Web Fetch handler under the fetch property. TanStack Start meets all these conditions.

This build plugin can be opted into via the intentionally private, undocumented build.enabled option, passed into @netlify/vite-plugin.

This also adds a new @netlify/vite-plugin-tanstack-start which just wraps @netlify/vite-plugin with this enabled.

At the moment, this only supports TanStack Start alpha, but this will be released imminently (presumably v.1.132 or so). As such, it inherits its requirements:

Vite 7+
Node.js 22.12.0+

Note that by wrapping @netlify/vite-plugin, @netlify/vite-plugin-tanstack-start also inherits all the former's dev functionality.

Just in case someone were to (unnecessarily) configure both, this PR adds some logic to detect this and print an actionable warning.

To do

add tests
improve readme?
verify SPA mode
add logic to prevent duplicated @netlify/vite-plugin running twice?
~~[ ] add edge SSR support if easy~~

packages/vite-plugin-tanstack-start/package.json

serhalp · 2025-09-17T18:56:04Z

packages/vite-plugin-tanstack-start/package.json

+    "@tanstack/react-start": "alpha",
+    "@tanstack/solid-start": "alpha",


FIXME before merge (or fast follow, depending on how timing plays out)

these should be something like >=1.132.0

packages/vite-plugin/src/main.ts

packages/vite-plugin/package.json

serhalp · 2025-09-17T19:06:46Z

packages/vite-plugin/package.json

    "@netlify/dev": "4.5.9",
-    "@netlify/dev-utils": "^4.1.3"
+    "@netlify/dev-utils": "^4.1.3",
+    "dedent": "^1.7.0"


26 KB, zero dependencies, maintained: https://node-modules.dev/#install=dedent

worth it for proper syntax highlighting and syntax parsing in IDEs

This adds a framework-agnostic Vite build plugin that prepares a Vite app for deployment to Netlify. It expects that the Vite app has an `ssr` environment (and no other server environments to deploy) that has exactly one bundle entry and that this entry is a server request entry point, a module with a default export containing a Web Fetch handler under the `fetch` property. TanStack Start meets all these conditions. This build plugin can be opted into via the intentionally private, undocumented `build.enabled` option, passed into `@netlify/vite-plugin`. This also adds a new `@netlify/vite-plugin-tanstack-start` which just wraps `@netlify/vite-plugin` with this enabled. At the moment, this only supports TanStack Start `alpha`, but this will be released imminently (presumably v.1.132 or so). As such, it inherits its requirements: - Vite 7+ - Node.js 22.12.0+

packages/vite-plugin-tanstack-start/src/main.ts

serhalp · 2025-09-19T11:41:15Z

packages/vite-plugin-tanstack-start/test/fixtures/start-basic-alpha/package.json

+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@netlify/vite-plugin-tanstack-start": "file:../../..",


☝🏼 one of the only changes to the starter

serhalp · 2025-09-19T11:41:37Z

packages/vite-plugin-tanstack-start/test/fixtures/start-basic-alpha/vite.config.ts

+    }),
+    tanstackStart(),
+    viteReact(),
+    netlify(),


☝🏼 one of the only changes to the starter

serhalp · 2025-09-19T11:41:58Z

packages/vite-plugin-tanstack-start/test/fixtures/start-basic-alpha/netlify.toml

+[build]
+  command = "npm run build"
+  publish = "dist/client"


☝🏼 the last change to the starter

We will be able to remove need for this once netlify/build#6669 ships, right?

nope, framework detection doesn't occur on netlify deploy. this uses an existing site.

serhalp · 2025-09-19T11:43:10Z

packages/vite-plugin-tanstack-start/test/support/netlify-deploy.ts

File copied from remix-compute, simplified, and refactored away unnecessary dependencies

We're probably overdue for a shared helper in a package somewhere...

serhalp · 2025-09-19T11:45:58Z

packages/vite-plugin-tanstack-start/package.json

+  "description": "Vite plugin for TanStack Start on Netlify",
+  "type": "module",
+  "engines": {
+    "node": "^22.12.0"


this is going to be TanStack Start's supported range, so no use in supporting any greater

serhalp · 2025-09-19T11:46:42Z

packages/vite-plugin-tanstack-start/package.json

+  "peerDependencies": {
+    "@tanstack/react-start": "alpha",
+    "@tanstack/solid-start": "alpha",
+    "vite": ">=7.0.0"


this is going to be TanStack Start's supported range, so no use in supporting any greater

packages/vite-plugin-tanstack-start/README.md

serhalp · 2025-09-19T11:52:05Z

packages/vite-plugin/src/main.ts

   */
  middleware?: boolean
+
+  /** @private */


Alternatively, this could be a separate export from @netlify/vite-plugin? like /internal or something. or not exposed at all, one way or another. I liked this approach, but I don't feel strongly.

I don't know the intended behavior with @private, but this doesn't seem to prevent from build option from being shown to users (unless it requires some specific configuration, this was just default behavior in empty project I checked after installing npm packed version of vite plugin from this PR):

I don't necessarily think we shouldn't do it like this, but maybe we could duplicate

* This is currently only supported for TanStack Start projects.

to apply to build property as well and not just build.enabled? (or maybe move it there)

hrm. well, I added a more explicit callout: 84225cb. I think this is fine for now? we can always refactor later. I think it's fine to change it without majors.

serhalp · 2025-09-19T11:52:46Z

packages/vite-plugin/package.json

    "prepack": "npm run build",
    "test": "vitest run",
    "test:dev": "vitest",
-    "test:ci": "npm run build && vitest run",


this wasn't necessary. it was building twice in CI.

pieh · 2025-09-19T16:03:07Z

packages/vite-plugin-tanstack-start/vitest.config.ts

+export default defineConfig({
+  test: {
+    testTimeout: 15_000,
+    hookTimeout: 90_000,


I did have to bump this even more when trying to debug it on windows ... so maybe this is just still not enough ( I did see you bumped it at least once already )

But after that I did get

FAIL test/e2e/build.test.ts > build output when deployed to Netlify Error: Could not extract the URL from the build logs ❯ deploySite test/support/netlify-deploy.ts:65:11 63| const [url] = new RegExp(/https:.+\.netlify\.app/gm).exec(stdout) ?? [] 64| if (!url) { 65| throw new Error('Could not extract the URL from the build logs') | ^ 66| } 67| console.log(`🌍 Deployed site is live: ${url}`) ❯ test/e2e/build.test.ts:18:21

And checking _deploy.log I see CLI formatted the thing we match on like so:

╭───────────────────────── ⬥ Draft deploy is live ⬥ ─────────────────────────╮ │ │ │ Deployed draft to https://68cd7cef1a39c99933013541--phenomenal-hummingbi │ │ rd-d567fe.netlify.app │ │ │ ╰──────────────────────────────────────────────────────────────────────────────╯

... but even ignoring all that and checking deployed site - https://68cd7cef1a39c99933013541--phenomenal-hummingbird-d567fe.netlify.app/ it crashes with:

Sep 19, 05:59:36 PM: ERROR Uncaught Exception {"errorType":"Error","errorMessage":"Cannot find package 'react' imported from /var/task/.netlify/v1/functions/server.mjs","code":"ERR_MODULE_NOT_FOUND","stack":["Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'react' imported from /var/task/.netlify/v1/functions/server.mjs"," at Object.getPackageJSONURL (node:internal/modules/package_json_reader:268:9)"," at packageResolve (node:internal/modules/esm/resolve:774:81)"," at moduleResolve (node:internal/modules/esm/resolve:860:18)"," at moduleResolveWithNodePath (node:internal/modules/esm/resolve:990:14)"," at defaultResolve (node:internal/modules/esm/resolve:1033:79)"," at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:780:12)"," at #cachedDefaultResolve (node:internal/modules/esm/loader:704:25)"," at ModuleLoader.resolve (node:internal/modules/esm/loader:687:38)"," at ModuleLoader.getModuleJobForImport (node:internal/modules/esm/loader:305:38)"," at ModuleJob._link (node:internal/modules/esm/module_job:137:49)"]} Sep 19, 05:59:36 PM: INIT_REPORT Init Duration: 271.73 ms Phase: invoke Status: error Error Type: Runtime.Unknown Sep 19, 05:59:36 PM: f47e870f Duration: 341.44 ms Memory Usage: 106 MB

ugh, it looks like we don't test on Windows in remix-compute, where I copied the test helper from: https://github.com/netlify/remix-compute/tree/573bb9494e13bd1a4e858b76322ab112984db994/.github/workflows. so there are probably some latent issues there.

the url thing is easy to fix... looks like the boxen thing makes it sometimes wrap over two lines. Adding --json (but kept the rest of the logic) should fix that: d7b644e.

also bumped timeout even higher... let's see if we can at least fix the first 2 of 3 issues: 3962b51

I could switch it from pnpm to something else...? let me try changing it to npm.

or maybe one of these pnpm options could help 😕:

--package-import-method auto Clones/hardlinks or copies packages. The selected method depends from the file system --package-import-method clone Clone (aka copy-on-write) packages from the store --package-import-method copy Copy packages from the store --package-import-method hardlink Hardlink packages from the store

welp, I did fix the first two issues but debugging the third is a rabbit hole I can't afford right now, so I skipped Windows tests for now :(

pnpm seems to be problematic on Windows CI...

We'll do this in a separate PR to be safe.

follow-up to d117f25 You can't use `overrides` for a direct dependency unless the values are identical...

Because we now have framework-specific plugins that load our generic plugin, we should make sure nothing bad happens if a user also includes our generic plugin directly. I went down a few different paths here and this ended up seeming like the best approach: just warn when we detect multiple instances in dev. Build is tricky because by design our plugin will be instantiated once per environment (e.g. client + ssr). And it ends up generally not being a problem if it's duplicated in build anyway, just dev.

math is hard

also fix technically incorrect node version check

serhalp commented Sep 17, 2025

View reviewed changes

packages/vite-plugin-tanstack-start/package.json Outdated Show resolved Hide resolved

serhalp commented Sep 17, 2025

View reviewed changes

packages/vite-plugin/src/main.ts Outdated Show resolved Hide resolved

serhalp commented Sep 17, 2025

View reviewed changes

packages/vite-plugin/package.json Outdated Show resolved Hide resolved

serhalp commented Sep 17, 2025

View reviewed changes

serhalp force-pushed the serhalp/frb-1993-create-netlifyvite-plugin-tanstack-start branch 6 times, most recently from af6ec5e to a2a0061 Compare September 18, 2025 21:46

serhalp force-pushed the serhalp/frb-1993-create-netlifyvite-plugin-tanstack-start branch from 715c821 to f148fa5 Compare September 18, 2025 23:31

chore: try a longer hook timeout

7393ea1

serhalp commented Sep 19, 2025

View reviewed changes

packages/vite-plugin-tanstack-start/src/main.ts Outdated Show resolved Hide resolved

serhalp commented Sep 19, 2025

View reviewed changes

packages/vite-plugin-tanstack-start/README.md Outdated Show resolved Hide resolved

serhalp commented Sep 19, 2025

View reviewed changes

pieh reviewed Sep 19, 2025

View reviewed changes

serhalp added 5 commits September 19, 2025 13:00

refactor: remove unnecessary internal dep

e1f0722

fix(docs): fix incorrect options in readme

ab92bc5

fix(types): add clearer private callout

84225cb

chore: fix potential e2e deploy helper issue

d7b644e

ci: try even higher timeout for Windows

3962b51

serhalp added 10 commits September 19, 2025 13:38

chore: try npm for e2e fixture install

d117f25

pnpm seems to be problematic on Windows CI...

fix: revert vite plugin type fix for now

01f2a25

We'll do this in a separate PR to be safe.

chore: actually use npm correctly in deploy helper.

34aafb5

follow-up to d117f25 You can't use `overrides` for a direct dependency unless the values are identical...

chore: better error logging for failed e2e deploy

c57b877

chore: fix e2e deploy bug

d5fae8a

chore: actually bump e2e timeout

ee97397

math is hard

chore: improve e2e deploy logging

1e456c5

chore: try even higher Windows e2e timeout

b81b724

test: skip tanstack plugin Windows tests for now

2bbf206

also fix technically incorrect node version check

serhalp marked this pull request as ready for review September 21, 2025 20:38

serhalp requested review from a team as code owners September 21, 2025 20:38

pieh approved these changes Sep 22, 2025

View reviewed changes

pieh merged commit fd8b2cc into main Sep 22, 2025
20 of 21 checks passed

pieh deleted the serhalp/frb-1993-create-netlifyvite-plugin-tanstack-start branch September 22, 2025 11:03

token-generator-app bot mentioned this pull request Sep 22, 2025

chore: release main #456

Merged

pieh mentioned this pull request Sep 22, 2025

fix: set proper peer dependencies #458

Merged

		"@tanstack/react-start": "alpha",
		"@tanstack/solid-start": "alpha",

feat: add @netlify/vite-plugin-tanstack-start #455

feat: add @netlify/vite-plugin-tanstack-start #455

Uh oh!

Conversation

serhalp commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

To do

Uh oh!

Uh oh!

serhalp Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

serhalp Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add `@netlify/vite-plugin-tanstack-start` #455

feat: add `@netlify/vite-plugin-tanstack-start` #455

serhalp commented Sep 17, 2025 •

edited

Loading

serhalp Sep 17, 2025 •

edited

Loading

serhalp Sep 19, 2025 •

edited

Loading