From eb746beb74b59f19148a1d241564ecff0d850963 Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Thu, 19 Nov 2026 08:47:29 -0700 Subject: [PATCH 1/4] fix: replace deprecated Neon provisioning plugin --- .changeset/neon-explicit-database-setup.md | 5 ++ .../create-rwsdk/add-ons/neon/README.md | 18 ++++++-- .../neon/assets/_dot_env.example.append | 3 +- .../add-ons/neon/assets/neon-vite-plugin.ts | 10 ---- .../assets/src/app/components/demo-neon.tsx | 14 +++--- .../create-rwsdk/add-ons/neon/info.json | 8 +--- .../create-rwsdk/add-ons/neon/package.json | 3 +- .../frameworks/react/add-ons/neon/README.md | 17 +++++-- .../neon/assets/_dot_env.example.append | 3 +- .../add-ons/neon/assets/neon-vite-plugin.ts | 10 ---- .../neon/assets/src/routes/demo/neon.tsx | 14 +++--- .../frameworks/react/add-ons/neon/info.json | 8 +--- .../react/add-ons/neon/package.json | 3 +- packages/create/tests/neon-scaffold.test.ts | 46 +++++++++++++++++++ 14 files changed, 96 insertions(+), 66 deletions(-) create mode 100644 .changeset/neon-explicit-database-setup.md delete mode 100644 examples/custom-cli/create-rwsdk/add-ons/neon/assets/neon-vite-plugin.ts delete mode 100644 packages/create/src/frameworks/react/add-ons/neon/assets/neon-vite-plugin.ts create mode 100644 packages/create/tests/neon-scaffold.test.ts diff --git a/.changeset/neon-explicit-database-setup.md b/.changeset/neon-explicit-database-setup.md new file mode 100644 index 000000000..c518f0caa --- /dev/null +++ b/.changeset/neon-explicit-database-setup.md @@ -0,0 +1,5 @@ +--- +"@tanstack/create": patch +--- + +Replace the deprecated Neon Vite plugin with explicit database setup instructions, keeping app startup free of automatic database provisioning. diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/README.md b/examples/custom-cli/create-rwsdk/add-ons/neon/README.md index 480f40f81..246acc8e5 100644 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/README.md +++ b/examples/custom-cli/create-rwsdk/add-ons/neon/README.md @@ -1,8 +1,16 @@ -## Setting up Neon +## Neon setup -When running the `dev` command, `vite-plugin-neon-new` will identify there is not a database setup. It will then create and seed a claimable database. +Create a database and write its connection string to `.env`: -It is the same process as [Neon Launchpad](https://neon.new). +```sh +npx neon@9.6.3 claim create --env-pull --file .env +``` -> [!IMPORTANT] -> Claimable databases expire in 72 hours. +You can also use an existing Neon database. Set `VITE_DATABASE_URL` in `.env` to its connection string. +Claimable Neon writes `DATABASE_URL`. Copy that value to `VITE_DATABASE_URL` for this example. + +Run `db/init.sql` once in the Neon SQL Editor to create the demo table and seed its three todos. Repeating the script inserts the sample todos again. + +Start the app with your package manager's `dev` command. To keep a claimable database, run `npx neon@9.6.3 claim accept` before it expires. + +See https://neon.com/docs/reference/claimable-neon for database setup and claiming. diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/_dot_env.example.append b/examples/custom-cli/create-rwsdk/add-ons/neon/assets/_dot_env.example.append index 3bc2b0761..5ea3e4250 100644 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/_dot_env.example.append +++ b/examples/custom-cli/create-rwsdk/add-ons/neon/assets/_dot_env.example.append @@ -1,4 +1,3 @@ -# These will be automatically created by Neon Launchpad (https://neon.new). -# You will also need to +# Set this to your Neon database connection string. VITE_DATABASE_URL= VITE_DATABASE_URL_POOLER= diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/neon-vite-plugin.ts b/examples/custom-cli/create-rwsdk/add-ons/neon/assets/neon-vite-plugin.ts deleted file mode 100644 index 4953e748d..000000000 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/neon-vite-plugin.ts +++ /dev/null @@ -1,10 +0,0 @@ -import { postgres } from 'vite-plugin-neon-new' - -export default postgres({ - seed: { - type: 'sql-script', - path: 'db/init.sql', - }, - referrer: 'create-tanstack', - dotEnvKey: 'VITE_DATABASE_URL', -}) diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx b/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx index 42cbc212b..c49c6aa3f 100644 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx +++ b/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx @@ -99,19 +99,19 @@ function DBConnectionError() { /> -

Database Connection Issue

-
The Neon database is not connected.
+

Neon database not connected

-

Required Steps to Fix:

diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/info.json b/examples/custom-cli/create-rwsdk/add-ons/neon/info.json index d70132f4c..3a0aab690 100644 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/info.json +++ b/examples/custom-cli/create-rwsdk/add-ons/neon/info.json @@ -14,12 +14,6 @@ "jsName": "NeonDemo" } ], - "integrations": [ - { - "type": "vite-plugin", - "jsName": "neon", - "path": "neon-vite-plugin.ts" - } - ], + "integrations": [], "dependsOn": [] } diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/package.json b/examples/custom-cli/create-rwsdk/add-ons/neon/package.json index bf86bf460..38d0bccf4 100644 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/package.json +++ b/examples/custom-cli/create-rwsdk/add-ons/neon/package.json @@ -1,6 +1,5 @@ { "dependencies": { - "@neondatabase/serverless": "^1.0.0", - "vite-plugin-neon-new": "^0.8.0" + "@neondatabase/serverless": "^1.0.0" } } diff --git a/packages/create/src/frameworks/react/add-ons/neon/README.md b/packages/create/src/frameworks/react/add-ons/neon/README.md index 480f40f81..dbdaf5924 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/README.md +++ b/packages/create/src/frameworks/react/add-ons/neon/README.md @@ -1,8 +1,15 @@ -## Setting up Neon +## Neon setup -When running the `dev` command, `vite-plugin-neon-new` will identify there is not a database setup. It will then create and seed a claimable database. +Create a database and write its connection string to `.env`: -It is the same process as [Neon Launchpad](https://neon.new). +```sh +npx neon@9.6.3 claim create --env-pull --file .env +``` -> [!IMPORTANT] -> Claimable databases expire in 72 hours. +You can also use an existing Neon database. Set `DATABASE_URL` in `.env` to its connection string. + +Run `db/init.sql` once in the Neon SQL Editor to create the demo table and seed its three todos. Repeating the script inserts the sample todos again. + +Start the app with your package manager's `dev` command. To keep a claimable database, run `npx neon@9.6.3 claim accept` before it expires. + +See https://neon.com/docs/reference/claimable-neon for database setup and claiming. diff --git a/packages/create/src/frameworks/react/add-ons/neon/assets/_dot_env.example.append b/packages/create/src/frameworks/react/add-ons/neon/assets/_dot_env.example.append index 1a739d832..284134470 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/assets/_dot_env.example.append +++ b/packages/create/src/frameworks/react/add-ons/neon/assets/_dot_env.example.append @@ -1,4 +1,3 @@ -# These will be automatically created by Neon Launchpad (https://neon.new). -# You will also need to +# Set this to your Neon database connection string. DATABASE_URL= DATABASE_URL_POOLER= diff --git a/packages/create/src/frameworks/react/add-ons/neon/assets/neon-vite-plugin.ts b/packages/create/src/frameworks/react/add-ons/neon/assets/neon-vite-plugin.ts deleted file mode 100644 index 7f72b77a1..000000000 --- a/packages/create/src/frameworks/react/add-ons/neon/assets/neon-vite-plugin.ts +++ /dev/null @@ -1,10 +0,0 @@ -import { postgres } from 'vite-plugin-neon-new' - -export default postgres({ - seed: { - type: 'sql-script', - path: 'db/init.sql', - }, - referrer: 'create-tanstack', - dotEnvKey: 'DATABASE_URL', -}) diff --git a/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx b/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx index 3f35772f3..ff146fbc2 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx +++ b/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx @@ -122,24 +122,24 @@ function DBConnectionError() { />
-

Database Connection Issue

-
- The Neon database is not connected. -
+

Neon database not connected

-

Required Steps to Fix:

diff --git a/packages/create/src/frameworks/react/add-ons/neon/info.json b/packages/create/src/frameworks/react/add-ons/neon/info.json index 5d2cd96dd..3e926e53f 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/info.json +++ b/packages/create/src/frameworks/react/add-ons/neon/info.json @@ -17,11 +17,5 @@ "jsName": "NeonDemo" } ], - "integrations": [ - { - "type": "vite-plugin", - "jsName": "neon", - "path": "neon-vite-plugin.ts" - } - ] + "integrations": [] } diff --git a/packages/create/src/frameworks/react/add-ons/neon/package.json b/packages/create/src/frameworks/react/add-ons/neon/package.json index 9c723acc7..0fd965cc6 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/package.json +++ b/packages/create/src/frameworks/react/add-ons/neon/package.json @@ -1,6 +1,5 @@ { "dependencies": { - "@neondatabase/serverless": "^1.0.2", - "vite-plugin-neon-new": "^0.8.0" + "@neondatabase/serverless": "^1.0.2" } } diff --git a/packages/create/tests/neon-scaffold.test.ts b/packages/create/tests/neon-scaffold.test.ts new file mode 100644 index 000000000..288ca93da --- /dev/null +++ b/packages/create/tests/neon-scaffold.test.ts @@ -0,0 +1,46 @@ +import { describe, expect, it } from 'vitest' + +import { finalizeAddOns } from '../src/add-ons.js' +import { createApp } from '../src/create-app.js' +import { createMemoryEnvironment } from '../src/environment.js' +import { createFrameworkDefinition } from '../src/frameworks/react/index.js' +import type { Framework } from '../src/types.js' + +describe('Neon scaffold', () => { + it('requires explicit database setup instead of provisioning through Vite', async () => { + const { base, addOns, ...definition } = createFrameworkDefinition() + const framework: Framework = { + ...definition, + getFiles: () => Promise.resolve(Object.keys(base)), + getFileContents: (path) => Promise.resolve(base[path]), + getDeletedFiles: () => Promise.resolve([]), + getAddOns: () => addOns, + } + const { environment, output } = createMemoryEnvironment() + await createApp(environment, { + projectName: 'neon-app', + targetDir: '/neon-app', + framework, + mode: 'file-router', + typescript: true, + tailwind: true, + packageManager: 'npm', + git: false, + install: false, + intent: false, + chosenAddOns: await finalizeAddOns(framework, 'file-router', ['neon']), + addOnOptions: {}, + }) + + const manifest = JSON.parse(output.files['/neon-app/package.json']) + expect(manifest.dependencies['@neondatabase/serverless']).toBeDefined() + expect(manifest.dependencies['vite-plugin-neon-new']).toBeUndefined() + expect(output.files['/neon-app/neon-vite-plugin.ts']).toBeUndefined() + expect(output.files['/neon-app/vite.config.ts']).not.toContain('neon') + expect(output.files['/neon-app/db/init.sql']).toContain('CREATE TABLE') + expect(output.files['/neon-app/README.md']).toContain( + 'claim create --env-pull --file .env', + ) + expect(output.commands).toEqual([]) + }) +}) From 788d71fa1a0bf9b9710324b7a8dda19832eac2f2 Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Thu, 19 Nov 2026 09:18:30 -0700 Subject: [PATCH 2/4] fix(create): clarify Neon seeding and claim transfer --- .../create-rwsdk/add-ons/neon/README.md | 19 ++++++++++++++----- .../assets/src/app/components/demo-neon.tsx | 15 +++++++++------ .../frameworks/react/add-ons/neon/README.md | 16 ++++++++++++---- .../neon/assets/src/routes/demo/neon.tsx | 14 +++++++++----- packages/create/tests/neon-scaffold.test.ts | 6 ++++++ 5 files changed, 50 insertions(+), 20 deletions(-) diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/README.md b/examples/custom-cli/create-rwsdk/add-ons/neon/README.md index 246acc8e5..084fc3c71 100644 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/README.md +++ b/examples/custom-cli/create-rwsdk/add-ons/neon/README.md @@ -1,16 +1,25 @@ ## Neon setup -Create a database and write its connection string to `.env`: +Create a claimable database and write its connection string to `.env`: ```sh npx neon@9.6.3 claim create --env-pull --file .env ``` -You can also use an existing Neon database. Set `VITE_DATABASE_URL` in `.env` to its connection string. -Claimable Neon writes `DATABASE_URL`. Copy that value to `VITE_DATABASE_URL` for this example. +The CLI writes `DATABASE_URL`. Copy that value to `VITE_DATABASE_URL` in `.env` for this example. -Run `db/init.sql` once in the Neon SQL Editor to create the demo table and seed its three todos. Repeating the script inserts the sample todos again. +Seed the claimable database from this project directory: -Start the app with your package manager's `dev` command. To keep a claimable database, run `npx neon@9.6.3 claim accept` before it expires. +```sh +npx neon@9.6.3 psql --role-name neondb_owner -- -f db/init.sql +``` + +This creates the demo table and its three sample todos. Run it once, repeating the script inserts the sample todos again. + +For an existing Neon database, skip creation, set `VITE_DATABASE_URL` in `.env` to its connection string, and run `db/init.sql` once in that project's SQL Editor. The SQL Editor requires an owned project, so use the CLI command above before claiming. + +Start the app with your package manager's `dev` command. + +To keep a claimable database, run `npx neon@9.6.3 claim accept` before it expires and complete the transfer in the browser. Claiming revokes the temporary database password. Get a fresh connection string from the destination project in the Neon Console, replace `VITE_DATABASE_URL` in `.env`, and restart the dev server. `claim accept` does not refresh `.env` for you. See https://neon.com/docs/reference/claimable-neon for database setup and claiming. diff --git a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx b/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx index c49c6aa3f..d52e2b7ce 100644 --- a/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx +++ b/examples/custom-cli/create-rwsdk/add-ons/neon/assets/src/app/components/demo-neon.tsx @@ -109,9 +109,11 @@ function DBConnectionError() {
Create a database with{' '} npx neon@9.6.3 claim create --env-pull --file .env, - then run{' '} - db/init.sql{' '} - once in the Neon SQL Editor to create and seed the demo table + then seed it once with{' '} + + npx neon@9.6.3 psql --role-name neondb_owner -- -f db/init.sql + + .
  • @@ -119,12 +121,13 @@ function DBConnectionError() { 2
    - Set the{' '} + Copy the CLI's DATABASE_URL value to{' '} VITE_DATABASE_URL {' '} - environment variable to the connection string of your Neon - database in .env, then restart the dev server + in .env. After claiming, replace it with a fresh + connection string from the Neon Console. Restart the dev server + after changing .env.
  • diff --git a/packages/create/src/frameworks/react/add-ons/neon/README.md b/packages/create/src/frameworks/react/add-ons/neon/README.md index dbdaf5924..8e0426c8a 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/README.md +++ b/packages/create/src/frameworks/react/add-ons/neon/README.md @@ -1,15 +1,23 @@ ## Neon setup -Create a database and write its connection string to `.env`: +Create a claimable database and write its connection string to `.env`: ```sh npx neon@9.6.3 claim create --env-pull --file .env ``` -You can also use an existing Neon database. Set `DATABASE_URL` in `.env` to its connection string. +Seed the claimable database from this project directory: -Run `db/init.sql` once in the Neon SQL Editor to create the demo table and seed its three todos. Repeating the script inserts the sample todos again. +```sh +npx neon@9.6.3 psql --role-name neondb_owner -- -f db/init.sql +``` + +This creates the demo table and its three sample todos. Run it once, repeating the script inserts the sample todos again. + +For an existing Neon database, skip creation, set `DATABASE_URL` in `.env` to its connection string, and run `db/init.sql` once in that project's SQL Editor. The SQL Editor requires an owned project, so use the CLI command above before claiming. + +Start the app with your package manager's `dev` command. -Start the app with your package manager's `dev` command. To keep a claimable database, run `npx neon@9.6.3 claim accept` before it expires. +To keep a claimable database, run `npx neon@9.6.3 claim accept` before it expires and complete the transfer in the browser. Claiming revokes the temporary database password. Get a fresh connection string from the destination project in the Neon Console, replace `DATABASE_URL` in `.env`, and restart the dev server. `claim accept` does not refresh `.env` for you. See https://neon.com/docs/reference/claimable-neon for database setup and claiming. diff --git a/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx b/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx index ff146fbc2..0184f03e2 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx +++ b/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx @@ -130,16 +130,20 @@ function DBConnectionError() {
    Create a database with{' '} npx neon@9.6.3 claim create --env-pull --file .env, - then run db/init.sql once in the Neon SQL Editor to - create and seed the demo table. + then seed it once with{' '} + + npx neon@9.6.3 psql --role-name neondb_owner -- -f db/init.sql + + .
  • 2
    - Set the DATABASE_URL environment variable to the - connection string of your Neon database in .env, then - restart the dev server + Use DATABASE_URL in .env for the + connection string. After claiming the database, replace it with a + fresh connection string from the Neon Console. Restart the dev + server after changing .env.
  • diff --git a/packages/create/tests/neon-scaffold.test.ts b/packages/create/tests/neon-scaffold.test.ts index 288ca93da..ff3c98fb7 100644 --- a/packages/create/tests/neon-scaffold.test.ts +++ b/packages/create/tests/neon-scaffold.test.ts @@ -41,6 +41,12 @@ describe('Neon scaffold', () => { expect(output.files['/neon-app/README.md']).toContain( 'claim create --env-pull --file .env', ) + expect(output.files['/neon-app/README.md']).toContain( + 'psql --role-name neondb_owner -- -f db/init.sql', + ) + expect(output.files['/neon-app/README.md']).toContain( + 'replace `DATABASE_URL` in `.env`, and restart the dev server', + ) expect(output.commands).toEqual([]) }) }) From 6f5d82988d32c15a64827c510022bcdf3bf0735a Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Thu, 19 Nov 2026 09:55:31 -0700 Subject: [PATCH 3/4] fix(create): show Neon recovery when queries fail --- .../add-ons/neon/assets/src/routes/demo/neon.tsx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx b/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx index 0184f03e2..cd2236585 100644 --- a/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx +++ b/packages/create/src/frameworks/react/add-ons/neon/assets/src/routes/demo/neon.tsx @@ -6,14 +6,18 @@ import { getClient } from '#/db' const getTodos = createServerFn({ method: 'GET', }).handler(async () => { - const client = await getClient() - if (!client) { + try { + const client = await getClient() + if (!client) { + return undefined + } + return (await client.query(`SELECT * FROM todos`)) as Array<{ + id: number + title: string + }> + } catch { return undefined } - return (await client.query(`SELECT * FROM todos`)) as Array<{ - id: number - title: string - }> }) const insertTodo = createServerFn({ From bcae22f9173ce1ee537ba8bb47c076ed4fafa36d Mon Sep 17 00:00:00 2001 From: Tanner Linsley Date: Thu, 19 Nov 2026 09:59:45 -0700 Subject: [PATCH 4/4] test(create): cover Neon query recovery --- packages/cli/tests-e2e/neon-smoke.spec.ts | 58 +++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 packages/cli/tests-e2e/neon-smoke.spec.ts diff --git a/packages/cli/tests-e2e/neon-smoke.spec.ts b/packages/cli/tests-e2e/neon-smoke.spec.ts new file mode 100644 index 000000000..4087e3f59 --- /dev/null +++ b/packages/cli/tests-e2e/neon-smoke.spec.ts @@ -0,0 +1,58 @@ +import fs from 'node:fs' +import path from 'node:path' +import { expect, test } from '@playwright/test' +import { createReactAppFixture, optimizePageForFastE2E } from './helpers' + +for (const rejects of [true, false]) { + test(`@matrix Neon ${rejects ? 'shows recovery after a rejected query' : 'renders successful query results'}`, async ({ + page, + }) => { + const app = await createReactAppFixture({ + appName: `neon-query-${rejects ? 'failure' : 'success'}`, + addOns: ['neon'], + runQualityGatesChecks: true, + afterCreate: async (dir) => { + fs.writeFileSync( + path.join(dir, 'src/db.ts'), + ` +export async function getClient() { + return { query: async (..._args: unknown[]) => { + ${rejects ? "throw new Error('Local test: password authentication failed')" : "return [{ id: 1, title: 'Local query success' }]"} + } } +} +`, + ) + }, + }) + try { + await optimizePageForFastE2E(page) + await page.goto(app.url + '/demo/neon') + if (rejects) { + await expect( + page.getByRole('heading', { + name: 'Neon database not connected', + exact: true, + }), + ).toBeVisible() + await expect( + page.getByText('a fresh connection string from the Neon Console', { + exact: false, + }), + ).toBeVisible() + } else { + await expect( + page.getByText('Local query success', { exact: true }), + ).toBeVisible() + await expect( + page.getByRole('heading', { + name: 'Neon database not connected', + exact: true, + }), + ).toHaveCount(0) + } + } finally { + await app.stop() + await app.cleanup() + } + }) +}