fix(pg-cloudflare): use conditional export to support bundlers that don't know about cloudflare:sockets

Author: CHC383

packages/pg-bundler-test/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "pg-bundler-test",
+  "version": "0.0.0",
+  "description": "Test bundlers with pg-cloudflare, https://github.com/brianc/node-postgres/issues/3452",
+  "license": "MIT",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "pg-cloudflare": "^1.2.5",
+    "webpack": "^5.99.9",
+    "webpack-cli": "^6.0.1",
+    "rollup": "^4.41.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "vite": "^6.3.5"
+  },
+  "scripts": {
+    "test": "yarn webpack && yarn rollup && yarn vite",
+    "webpack": "webpack --config webpack-empty.config.js && webpack --config webpack-cloudflare.config.js",
+    "rollup": "rollup --config rollup-empty.config.js --failAfterWarnings && rollup --config rollup-cloudflare.config.js --failAfterWarnings",
+    "vite": "vite build --config vite-empty.config.js && vite build --config vite-cloudflare.config.js"
+  }
+}

packages/pg-bundler-test/rollup-cloudflare.config.js

@@ -0,0 +1,15 @@
+import { defineConfig } from 'rollup'
+import { nodeResolve } from '@rollup/plugin-node-resolve'
+import commonjs from '@rollup/plugin-commonjs'
+
+const config = defineConfig({
+  input: 'src/index.js',
+  output: {
+    file: 'dist/rollup-cloudflare.js',
+    format: 'es',
+  },
+  plugins: [nodeResolve({ exportConditions: ['import', 'cloudflare'], preferBuiltins: true }), commonjs()],
+  external: ['cloudflare:sockets'],
+})
+
+export default config

packages/pg-bundler-test/rollup-empty.config.js

@@ -0,0 +1,14 @@
+import { defineConfig } from 'rollup'
+import { nodeResolve } from '@rollup/plugin-node-resolve'
+import commonjs from '@rollup/plugin-commonjs'
+
+const config = defineConfig({
+  input: 'src/index.js',
+  output: {
+    file: 'dist/rollup-empty.js',
+    format: 'es',
+  },
+  plugins: [nodeResolve(), commonjs()],
+})
+
+export default config

packages/pg-bundler-test/src/index.js

@@ -0,0 +1 @@
+import 'pg-cloudflare'

packages/pg-bundler-test/vite-cloudflare.config.js

@@ -0,0 +1,24 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import commonjs from '@rollup/plugin-commonjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  build: {
+    emptyOutDir: false,
+    lib: {
+      entry: resolve(__dirname, 'src/index.js'),
+      fileName: 'vite-cloudflare',
+      formats: ['es'],
+    },
+    rollupOptions: {
+      external: ['cloudflare:sockets'],
+    },
+  },
+  resolve: {
+    conditions: ['import', 'cloudflare'],
+  },
+  plugins: [commonjs()],
+})

packages/pg-bundler-test/vite-empty.config.js

@@ -0,0 +1,16 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  build: {
+    lib: {
+      emptyOutDir: false,
+      entry: resolve(__dirname, 'src/index.js'),
+      fileName: 'vite-empty',
+      formats: ['es'],
+    },
+  },
+})

packages/pg-bundler-test/webpack-cloudflare.config.js

@@ -0,0 +1,15 @@
+import webpack from 'webpack'
+
+export default {
+  mode: 'production',
+  output: {
+    filename: 'webpack-cloudflare.js',
+  },
+  resolve: { conditionNames: ['import', 'cloudflare'] },
+  plugins: [
+    // ignore cloudflare:sockets imports
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^cloudflare:sockets$/,
+    }),
+  ],
+}

packages/pg-bundler-test/webpack-empty.config.js

@@ -0,0 +1,6 @@
+export default {
+  mode: 'production',
+  output: {
+    filename: 'webpack-empty.js',
+  },
+}

packages/pg-cloudflare/README.md

@@ -10,6 +10,43 @@
 npm i --save-dev pg-cloudflare
 ```
 
+The package uses conditional exports to support bundlers that don't know about
+`cloudflare:sockets`, so the consumer code by default imports an empty file. To
+enable the package, resolve to the `cloudflare` condition in your bundler's
+config. For example:
+
+- `webpack.config.js`
+  ```js
+  resolve: { conditionNames: [..., "cloudflare"] },
+  plugins: [
+    // ignore cloudflare:sockets imports
+    new webpack.IgnorePlugin({
+      resourceRegExp: /^cloudflare:sockets$/,
+    }),
+  ],
+  ```
+- `vite.config.js`
+  ```js
+  resolve: {
+    conditions: [..., "cloudflare"],
+  },
+  build: {
+    ...,
+    // don't try to bundle cloudflare:sockets
+    rollupOptions: {
+      external: [..., 'cloudflare:sockets'],
+    },
+  },
+  ```
+- `rollup.config.js`
+  ```js
+  plugins: [..., nodeResolve({ exportConditions: [..., 'cloudflare'] })],
+  // don't try to bundle cloudflare:sockets
+  external: [..., 'cloudflare:sockets'],
+  ```
+
+The concrete examples can be found in `packages/pg-bundler-test`.
+
 ## How to use conditionally, in non-Node.js environments
 
 As implemented in `pg` [here](https://github.com/brianc/node-postgres/commit/07553428e9c0eacf761a5d4541a3300ff7859578#diff-34588ad868ebcb232660aba7ee6a99d1e02f4bc93f73497d2688c3f074e60533R5-R13), a typical use case might look as follows, where in a Node.js environment the `net` module is used, while in a non-Node.js environment, where `net` is unavailable, `pg-cloudflare` is used instead, providing an equivalent interface:
@@ -21,15 +58,14 @@ module.exports.getStream = function getStream(ssl = false) {
     return net.Socket()
   }
   const { CloudflareSocket } = require('pg-cloudflare')
-  return new CloudflareSocket(ssl);
+  return new CloudflareSocket(ssl)
 }
 ```
 
 ## Node.js implementation of the Socket API proposal
 
 If you're looking for a way to rely on `connect()` as the interface you use to interact with raw sockets, but need this interface to be available in a Node.js environment, [`@arrowood.dev/socket`](https://github.com/Ethan-Arrowood/socket) provides a Node.js implementation of the Socket API.
 
-
 ### license
 
 The MIT License (MIT)

packages/pg-cloudflare/package.json

@@ -11,9 +11,11 @@
   },
   "exports": {
     ".": {
-      "import": "./esm/index.mjs",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
+      "cloudflare": {
+        "import": "./esm/index.mjs",
+        "require": "./dist/index.js"
+      },
+      "default": "./dist/empty.js"
     }
   },
   "scripts": {

packages/pg-esm-test/package.json

@@ -5,7 +5,7 @@
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "test": "node --test"
+    "test": "node --test --conditions=cloudflare"
   },
   "keywords": [
     "postgres",