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..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,8 +1,25 @@
-## 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 claimable 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.
+The CLI writes `DATABASE_URL`. Copy that value to `VITE_DATABASE_URL` in `.env` for this example.
+
+Seed the claimable database from this project directory:
+
+```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/_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..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
@@ -99,19 +99,21 @@ function DBConnectionError() {
/>
-
Database Connection Issue
- The Neon database is not connected.
+ Neon database not connected
-
Required Steps to Fix:
-
1
- Use the{' '}
- db/init.sql{' '}
- file to create the database
+ Create a database with{' '}
+ npx neon@9.6.3 claim create --env-pull --file .env,
+ 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{' '}
- DATABASE_URL
+ VITE_DATABASE_URL
{' '}
- environment variable to the connection string of your Neon
- database
+ 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/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/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()
+ }
+ })
+}
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..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,8 +1,23 @@
-## 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 claimable 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.
+Seed the claimable database from this project directory:
+
+```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.
+
+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/_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..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({
@@ -122,24 +126,28 @@ function DBConnectionError() {
/>
- Database Connection Issue
-
- The Neon database is not connected.
-
+ Neon database not connected
-
Required Steps to Fix:
-
1
- Use the db/init.sql file to create the database
+ Create a database with{' '}
+ npx neon@9.6.3 claim create --env-pull --file .env,
+ 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
+ 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/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..ff3c98fb7
--- /dev/null
+++ b/packages/create/tests/neon-scaffold.test.ts
@@ -0,0 +1,52 @@
+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.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([])
+ })
+})