feat(client): add /browser entrypoint to prisma-client (#28068)

This PR replaces #27978.
It partially addresses #27341.

Author: jkomyno

packages/client-generator-ts/src/TSClient/GenerateContext.ts

@@ -7,6 +7,7 @@ import { GenericArgsInfo } from '../GenericsArgsInfo'
 export interface GenerateContextOptions {
   dmmf: DMMFHelper
   genericArgsInfo: GenericArgsInfo
+  runtimeBase: string
   runtimeImport: string
   outputFileName: FileNameMapper
   importFileName: FileNameMapper
@@ -16,6 +17,7 @@ export interface GenerateContextOptions {
 export class GenerateContext implements GenerateContextOptions {
   dmmf: DMMFHelper
   genericArgsInfo: GenericArgsInfo
+  runtimeBase: string
   runtimeImport: string
   outputFileName: FileNameMapper
   importFileName: FileNameMapper
@@ -24,13 +26,15 @@ export class GenerateContext implements GenerateContextOptions {
   constructor({
     dmmf,
     genericArgsInfo,
+    runtimeBase,
     runtimeImport,
     outputFileName,
     importFileName,
     generator,
   }: GenerateContextOptions) {
     this.dmmf = dmmf
     this.genericArgsInfo = genericArgsInfo
+    this.runtimeBase = runtimeBase
     this.runtimeImport = runtimeImport
     this.outputFileName = outputFileName
     this.importFileName = importFileName

packages/client-generator-ts/src/TSClient/ModelExports.ts

@@ -0,0 +1,27 @@
+import * as ts from '@prisma/ts-builders'
+
+import { GenerateContext } from './GenerateContext'
+
+export function modelExports(context: GenerateContext): string[] {
+  return (
+    Object.values(context.dmmf.typeAndModelMap)
+      // choose models that have output types
+      .filter((model) => context.dmmf.outputTypeMap.model[model.name])
+
+      // generate export statements
+      .map((model) => {
+        const docLines = model.documentation ?? ''
+        const modelLine = `Model ${model.name}\n`
+        const docs = `${modelLine}${docLines}`
+        const suffix = 'Model'
+
+        const modelTypeExport = ts
+          // e.g., `export type User = Prisma.UserModel` when `model.name` is `User`
+          .moduleExport(ts.typeDeclaration(model.name, ts.namedType(`Prisma.${model.name}${suffix}`)))
+          // add JSDoc comment with the model name and documentation
+          .setDocComment(ts.docComment(docs))
+
+        return ts.stringify(modelTypeExport)
+      })
+  )
+}

packages/client-generator-ts/src/TSClient/TSClient.ts

@@ -5,12 +5,14 @@ import { generatedFileNameMapper, importFileNameMapper } from '../file-extension
 import type { FileMap } from '../generateClient'
 import { GenerateClientOptions } from '../generateClient'
 import { GenericArgsInfo } from '../GenericsArgsInfo'
+import { createBrowserFile } from './file-generators/BrowserFile'
 import { createClassFile } from './file-generators/ClassFile'
 import { createClientFile } from './file-generators/ClientFile'
 import { createCommonInputTypeFiles } from './file-generators/CommonInputTypesFile'
 import { createEnumsFile } from './file-generators/EnumsFile'
 import { createModelFile } from './file-generators/ModelFile'
 import { createModelsFile } from './file-generators/ModelsFile'
+import { createPrismaNamespaceBrowserFile } from './file-generators/PrismaNamespaceBrowserFile'
 import { createPrismaNamespaceFile } from './file-generators/PrismaNamespaceFile'
 import { GenerateContext } from './GenerateContext'
 
@@ -44,6 +46,7 @@ export class TSClient {
     const context = new GenerateContext({
       dmmf: this.dmmf,
       genericArgsInfo: this.genericsInfo,
+      runtimeBase: this.options.runtimeBase,
       runtimeImport: `${this.options.runtimeBase}/${this.options.runtimeName}`,
       outputFileName: generatedFileNameMapper(this.options.generatedFileExtension),
       importFileName: importFileNameMapper(this.options.importFileExtension),
@@ -61,12 +64,14 @@ export class TSClient {
 
     return {
       [context.outputFileName('client')]: createClientFile(context, this.options),
+      [context.outputFileName('browser')]: createBrowserFile(context, this.options),
       [context.outputFileName('enums')]: createEnumsFile(context),
       [context.outputFileName('commonInputTypes')]: createCommonInputTypeFiles(context),
       [context.outputFileName('models')]: createModelsFile(context, modelNames),
       models: modelsFileMap,
       internal: {
         [context.outputFileName('prismaNamespace')]: createPrismaNamespaceFile(context, this.options),
+        [context.outputFileName('prismaNamespaceBrowser')]: createPrismaNamespaceBrowserFile(context),
         [context.outputFileName('class')]: createClassFile(context, this.options),
       },
     }

packages/client-generator-ts/src/TSClient/file-generators/BrowserFile.ts

@@ -0,0 +1,29 @@
+import { getClientEngineType } from '@prisma/internals'
+
+import { GenerateContext } from '../GenerateContext'
+import { modelExports } from '../ModelExports'
+import { TSClientOptions } from '../TSClient'
+
+const jsDocHeader = `/*
+ * This file should be your main import to use Prisma-related types and utilities in a browser. 
+ * Use it to get access to models, enums, and input types.
+ * 
+ * This file does not contain a \`PrismaClient\` class, nor several other helpers that are intended as server-side only.
+ * See \`client.ts\` for the standard, server-side entry point.
+ *
+ * 🟢 You can import this file directly.
+ */
+`
+
+export function createBrowserFile(context: GenerateContext, options: TSClientOptions): string {
+  const clientEngineType = getClientEngineType(options.generator)
+  options.generator.config.engineType = clientEngineType
+
+  return `${jsDocHeader}
+import * as Prisma from '${context.importFileName('./internal/prismaNamespaceBrowser')}'
+export { Prisma }
+export * as $Enums from '${context.importFileName('./enums')}'
+export * from '${context.importFileName('./enums')}';
+${modelExports(context).join('\n')}
+`
+}

packages/client-generator-ts/src/TSClient/file-generators/ClientFile.ts

@@ -6,12 +6,14 @@ import * as ts from '@prisma/ts-builders'
 import { ModuleFormat } from '../../module-format'
 import { buildNFTAnnotations } from '../../utils/buildNFTAnnotations'
 import { GenerateContext } from '../GenerateContext'
+import { modelExports } from '../ModelExports'
 import { getPrismaClientClassDocComment } from '../PrismaClient'
 import { TSClientOptions } from '../TSClient'
 
 const jsDocHeader = `/*
  * This file should be your main import to use Prisma. Through it you get access to all the models, enums, and input types.
- *
+ * If you're looking for something you can import in the client-side of your application, please refer to the \`browser.ts\` file instead.
+ * 
  * 🟢 You can import this file directly.
  */
 `
@@ -65,20 +67,6 @@ export function createClientFile(context: GenerateContext, options: TSClientOpti
     ),
   ].map((e) => ts.stringify(e))
 
-  const modelExports = Object.values(context.dmmf.typeAndModelMap)
-    .filter((model) => context.dmmf.outputTypeMap.model[model.name])
-    .map((model) => {
-      const docLines = model.documentation ?? ''
-      const modelLine = `Model ${model.name}\n`
-      const docs = `${modelLine}${docLines}`
-
-      const modelTypeExport = ts
-        .moduleExport(ts.typeDeclaration(model.name, ts.namedType(`Prisma.${model.name}Model`)))
-        .setDocComment(ts.docComment(docs))
-
-      return ts.stringify(modelTypeExport)
-    })
-
   const binaryTargets =
     clientEngineType === ClientEngineType.Library
       ? (Object.keys(options.binaryPaths.libqueryEngine ?? {}) as BinaryTarget[])
@@ -97,7 +85,7 @@ export { Prisma }
 
 ${buildNFTAnnotations(options.edge || !options.copyEngine, clientEngineType, binaryTargets, relativeOutdir)}
 
-${modelExports.join('\n')}
+${modelExports(context).join('\n')}
 `
 }
 

packages/client-generator-ts/src/TSClient/file-generators/CommonInputTypesFile.ts

@@ -12,7 +12,7 @@ const jsDocHeader = `/*
 
 export function createCommonInputTypeFiles(context: GenerateContext) {
   const imports = [
-    ts.moduleImport(context.runtimeImport).asNamespace('runtime'),
+    ts.moduleImport(context.runtimeImport).asNamespace('runtime').typeOnly(),
     ts.moduleImport(context.importFileName(`./enums`)).asNamespace('$Enums'),
     ts.moduleImport(context.importFileName(`./internal/prismaNamespace`)).asNamespace('Prisma').typeOnly(),
   ].map((i) => ts.stringify(i))

packages/client-generator-ts/src/TSClient/file-generators/ModelFile.ts

@@ -12,7 +12,7 @@ export function createModelFile(context: GenerateContext, modelName: string): st
 `
 
   const imports = [
-    ts.moduleImport(context.runtimeImport).asNamespace('runtime'),
+    ts.moduleImport(context.runtimeImport).asNamespace('runtime').typeOnly(),
     ts.moduleImport(context.importFileName(`../enums`)).asNamespace('$Enums').typeOnly(),
     ts.moduleImport(context.importFileName(`../internal/prismaNamespace`)).asNamespace('Prisma').typeOnly(),
   ]

packages/client-generator-ts/src/TSClient/file-generators/PrismaNamespaceBrowserFile.ts

@@ -0,0 +1,38 @@
+import * as ts from '@prisma/ts-builders'
+
+import { Enum } from '../Enum'
+import { GenerateContext } from '../GenerateContext'
+
+const jsDocHeader = `/*
+ * WARNING: This is an internal file that is subject to change!
+ *
+ * 🛑 Under no circumstances should you import this file directly! 🛑
+ *
+ * All exports from this file are wrapped under a \`Prisma\` namespace object in the browser.ts file.
+ * While this enables partial backward compatibility, it is not part of the stable public API.
+ *
+ * If you are looking for your Models, Enums, and Input Types, please import them from the respective
+ * model files in the \`model\` directory!
+ */
+`
+export function createPrismaNamespaceBrowserFile(context: GenerateContext): string {
+  const prismaEnums = context.dmmf.schema.enumTypes.prisma?.map((type) => new Enum(type, true).toTS())
+
+  return `${jsDocHeader}
+${ts.stringify(ts.moduleImport(`${context.runtimeBase}/index-browser`).asNamespace('runtime'))}
+export type * from '${context.importFileName(`../models`)}'
+export type * from '${context.importFileName(`./prismaNamespace`)}'
+export const Decimal = runtime.Decimal
+${new Enum(
+  {
+    name: 'ModelName',
+    values: context.dmmf.mappings.modelOperations.map((m) => m.model),
+  },
+  true,
+).toTS()}
+/**
+ * Enums
+ */
+${prismaEnums?.join('\n\n')}
+`
+}

packages/client/helpers/build.ts

@@ -94,14 +94,18 @@ function wasmBindgenRuntimeConfig(
 }
 
 // we define the config for browser
-const browserBuildConfig: BuildOptions = {
-  name: 'browser',
-  entryPoints: ['src/runtime/index-browser.ts'],
-  outfile: 'runtime/index-browser',
-  target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
-  bundle: true,
-  minify: shouldMinify,
-  sourcemap: 'linked',
+function browserBuildConfigs(): BuildOptions[] {
+  return MODULE_FORMATS.map((format) => ({
+    format,
+    name: 'browser',
+    entryPoints: ['src/runtime/index-browser.ts'],
+    outfile: 'runtime/index-browser',
+    outExtension: getOutExtension(format),
+    target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
+    bundle: true,
+    minify: shouldMinify,
+    sourcemap: 'linked',
+  }))
 }
 
 /**
@@ -308,7 +312,7 @@ function* allWasmBindgenRuntimeConfigs(): Generator<BuildOptions> {
 void build([
   generatorBuildConfig,
   ...allNodeRuntimeBuildConfigs(),
-  browserBuildConfig,
+  ...browserBuildConfigs(),
   edgeRuntimeBuildConfig,
   edgeEsmRuntimeBuildConfig,
   ...allWasmEdgeRuntimeConfigs(),

packages/client/package.json

@@ -136,6 +136,12 @@
       "import": "./runtime/react-native.js",
       "default": "./runtime/react-native.js"
     },
+    "./runtime/index-browser": {
+      "types": "./runtime/index-browser.d.ts",
+      "require": "./runtime/index-browser.js",
+      "import": "./runtime/index-browser.mjs",
+      "default": "./runtime/index-browser.mjs"
+    },
     "./generator-build": {
       "require": "./generator-build/index.js",
       "import": "./generator-build/index.js",