Registry / database / neon-new

neon-new

JSON →
library0.14.0jsnpmunverified

`neon-new` (version 0.14.0) is a specialized command-line interface (CLI) and Software Development Kit (SDK) designed to facilitate the rapid, ephemeral provisioning of new, claimable Neon PostgreSQL databases. It aims to eliminate initial setup friction by allowing developers to instantiate a functional database with a single command or function call, without requiring immediate sign-up. The package currently ships with TypeScript types and targets Node.js environments. Its primary differentiating feature is the speed and ease of obtaining a fully functional PostgreSQL connection string, which is highly beneficial for rapid prototyping, local development, and CI/CD environments where temporary, on-demand databases are advantageous. While not having a strictly defined release cadence, the project is under active development, indicated by its pre-1.0.0 versioning, and has seen frequent updates. Users should be aware that databases generated this way are temporary and will expire if not formally claimed within 72 hours, making them ideal for short-lived use cases or as an initial stepping stone before migrating to a persistent, owned Neon project.

npm install neon-new
INSTALL
IMPORT
SIG · NEON-NEW
N
neon-new
databasejavascriptv0.14.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

instantPostgres
import { instantPostgres } from 'neon-new/sdk'
const { instantPostgres } = require('neon-new/sdk')
The SDK module (`neon-new/sdk`) is an ES Module and should be imported using `import` syntax in an ES Module context. CommonJS `require()` is not supported.
CLI usage (npm)
npx neon-new [options]
npm install -g neon-new && neon-new
The CLI is designed for ephemeral execution via `npx` (or `pnpx`, `yarn dlx`, `bunx`, `deno run npm:`), avoiding global installation and ensuring the latest version is used. Direct global installation is not the recommended pattern.

Demonstrates how to programmatically create a new Neon PostgreSQL database using the SDK, save its credentials to a .env file, and log the connection details and claim URL. Requires Node.js >= 22.

import { instantPostgres } from "neon-new/sdk"; import fs from 'fs'; import path from 'path'; async function setupDatabase() { const dotEnvPath = path.resolve(process.cwd(), '.env'); // Ensure .env file exists for the SDK to write to if (!fs.existsSync(dotEnvPath)) { fs.writeFileSync(dotEnvPath, ''); } console.log("Creating a new Neon database..."); const result = await instantPostgres({ referrer: process.env.NEON_APP_REFERRER || "checklist-day-example", // REQUIRED for SDK usage dotEnvFile: ".env", dotEnvKey: "DATABASE_URL", envPrefix: "PUBLIC_", settings: { logicalReplication: false, }, }); console.log("Database created successfully!"); console.log(`Pooled Connection String: ${result.databaseUrl}`); console.log(`Direct Connection String: ${result.databaseUrlDirect}`); console.log(`Claim URL (expires in 72h): ${result.claimUrl}`); console.log(`Credentials saved to ${dotEnvPath}`); // To connect, you would typically use a PostgreSQL client library (e.g., 'pg'): // import { Client } from 'pg'; // const client = new Client({ connectionString: result.databaseUrl }); // await client.connect(); // const res = await client.query('SELECT NOW()'); // console.log('Database time:', res.rows[0].now); // await client.end(); } setupDatabase().catch(console.error);
neon-new --version
Debug
Known issues
breakingThis package requires Node.js version 22 or higher. Users on older Node.js versions will encounter an error during execution, as specified by the `engines.node` field.
fix
Upgrade your Node.js environment to version 22 or newer. Consider using a Node Version Manager (like `nvm` or `volta`) to manage different Node.js versions.
affects: >=0.0.1
gotchaThe `referrer` option is a mandatory parameter when invoking the `instantPostgres` function from the SDK. Failing to provide a referrer string will result in a runtime error.
fix
Always provide a `referrer` string in the options object, for example: `instantPostgres({ referrer: 'your-app-name', ... })`.
affects: >=0.0.1
gotchaDatabases provisioned via `neon-new` are temporary by default and will automatically expire if not formally claimed by a Neon account within 72 hours. This is a critical consideration for data persistence.
fix
For long-term usage, ensure you visit the provided `claimUrl` within the 72-hour window to link the database to your Neon account. For ephemeral use, be aware of the data lifetime.
affects: >=0.0.1
gotchaThe package is currently in a pre-1.0.0 state (version 0.14.0). While actively developed, the API surface, configuration options, and behaviors might be subject to change in future minor or patch releases without strictly adhering to semantic versioning for breaking changes (as would be expected for versions 1.0.0+).
fix
It is advisable to pin your `neon-new` dependency to an exact version or to thoroughly review release notes when upgrading to new versions to anticipate and mitigate potential changes.
affects: >=0.0.1
Errors
Common errors & fixes
Error: The 'referrer' option is required.
Attempting to use the `instantPostgres` SDK function without providing the mandatory `referrer` parameter in its options object.
fix
Ensure you pass a `referrer` string in the options, such as `{ referrer: 'your-application-identifier' }`.
TypeError: instantPostgres is not a function
Using CommonJS `require()` syntax to import `instantPostgres` when the `neon-new/sdk` module is an ES Module, or importing from the wrong path.
fix
Switch to ES Module `import` syntax: `import { instantPostgres } from 'neon-new/sdk';`. Ensure your Node.js environment is configured for ESM (e.g., `"type": "module"` in `package.json`).
Error [ERR_REQUIRE_ESM]: require() of ES Module ...neon-new/sdk/index.js from ... not supported.
Attempting to `require()` an ES Module (`neon-new/sdk`) from a CommonJS context (e.g., a `.js` file without `"type": "module"` in `package.json`).
fix
To use the SDK, ensure your project's `package.json` contains `"type": "module"` or use `.mjs` file extensions for your source code. Then, use `import` statements.
Error: Your current Node.js version (vX.Y.Z) is not supported. Please upgrade to Node.js v22 or higher.
Executing the `neon-new` CLI or SDK in an environment with a Node.js version older than 22, which is explicitly required by the package.
fix
Upgrade your Node.js installation to version 22 or newer. If you need to manage multiple Node.js versions, tools like `nvm` are highly recommended.
Upgrade
Version history
0.14.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
neon-new — npm install neon-new · libregistry