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:

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:

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([]) + }) +})