feat(react-email): installation of UI without npm install (#2573)

Co-authored-by: Bu Kinoshita <6929565+bukinoshita@users.noreply.github.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 4 people

.changeset/spicy-shirts-unite.md

@@ -0,0 +1,5 @@
+---
+"react-email": minor
+---
+
+don't require installing @react-email/preview-server in the project, pack it into `$HOME/.react-email`

packages/preview-server/package.json

@@ -13,9 +13,7 @@
   },
   "main": "./index.mjs",
   "dependencies": {
-    "next": "16.0.10"
-  },
-  "devDependencies": {
+    "next": "16.0.10",
     "@babel/core": "7.26.10",
     "@babel/parser": "7.27.0",
     "@babel/traverse": "7.27.0",
@@ -29,33 +27,21 @@
     "@radix-ui/react-toggle": "1.1.10",
     "@radix-ui/react-toggle-group": "1.1.11",
     "@radix-ui/react-tooltip": "1.2.8",
+    "@react-email/tailwind": "workspace:2.0.3",
     "@react-email/body": "workspace:*",
     "@react-email/button": "workspace:*",
     "@react-email/code-block": "workspace:*",
     "@react-email/code-inline": "workspace:*",
-    "@react-email/components": "workspace:*",
     "@react-email/container": "workspace:*",
     "@react-email/heading": "workspace:*",
     "@react-email/hr": "workspace:*",
     "@react-email/img": "workspace:*",
     "@react-email/link": "workspace:*",
     "@react-email/preview": "workspace:*",
-    "@react-email/tailwind": "workspace:2.0.3",
     "@react-email/text": "workspace:*",
     "@tailwindcss/postcss": "4.1.17",
-    "@types/babel__core": "7.20.5",
-    "@types/babel__traverse": "7.20.7",
-    "@types/css-tree": "2.3.11",
-    "@types/fs-extra": "11.0.4",
-    "@types/mime-types": "2.1.4",
-    "@types/node": "22.19.7",
-    "@types/normalize-path": "3.0.2",
-    "@types/react": "19.0.10",
-    "@types/react-dom": "19.0.4",
-    "@types/webpack": "5.28.5",
     "clsx": "2.1.1",
     "colorjs.io": "0.5.2",
-    "cross-env": "^10.1.0",
     "esbuild": "0.25.10",
     "framer-motion": "12.23.22",
     "log-symbols": "4.1.0",
@@ -69,18 +55,32 @@
     "react": "19.0.0",
     "react-dom": "19.0.0",
     "resend": "6.4.0",
-    "rimraf": "^6.1.2",
-    "sharp": "0.34.5",
     "socket.io-client": "4.8.3",
     "sonner": "2.0.7",
     "source-map-js": "1.2.1",
     "stacktrace-parser": "0.1.11",
     "tailwind-merge": "3.4.0",
     "tailwindcss": "4.1.17",
-    "typescript": "5.8.3",
     "use-debounce": "10.0.6",
     "zod": "4.1.12"
   },
+  "devDependencies": {
+    "@react-email/components": "workspace:*",
+    "@types/babel__core": "7.20.5",
+    "@types/babel__traverse": "7.20.7",
+    "cross-env": "10.1.0",
+    "@types/css-tree": "2.3.11",
+    "rimraf": "6.1.2",
+    "sharp": "0.34.5",
+    "@types/fs-extra": "11.0.4",
+    "@types/mime-types": "2.1.4",
+    "@types/node": "22.19.7",
+    "@types/normalize-path": "3.0.2",
+    "@types/react": "19.0.10",
+    "@types/react-dom": "19.0.4",
+    "@types/webpack": "5.28.5",
+    "typescript": "5.8.3"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

packages/react-email/package.json

@@ -35,15 +35,15 @@
     "debounce": "^2.0.0",
     "esbuild": "^0.25.0",
     "glob": "^11.0.0",
-    "jiti": "2.4.2",
+    "jiti": "^2.4.2",
     "log-symbols": "^7.0.0",
     "mime-types": "^3.0.0",
     "normalize-path": "^3.0.0",
-    "nypm": "0.6.2",
     "ora": "^8.0.0",
-    "prompts": "2.4.2",
+    "prompts": "^2.4.2",
     "socket.io": "^4.8.1",
-    "tsconfig-paths": "4.2.0"
+    "tar": "^7.5.1",
+    "tsconfig-paths": "^4.2.0"
   },
   "devDependencies": {
     "@react-email/components": "workspace:*",

packages/react-email/src/commands/build.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { getPackages } from '@manypkg/get-packages';
 import logSymbols from 'log-symbols';
-import { installDependencies, type PackageManagerName, runScript } from 'nypm';
+import { type PackageManagerName, runScript } from 'nypm';
 import ora from 'ora';
 import {
   type EmailsDirectory,
@@ -17,13 +18,15 @@ interface Args {
 
 const setNextEnvironmentVariablesForBuild = async (
   emailsDirRelativePath: string,
-  builtPreviewAppPath: string,
+  appPath: string,
+  rootDirectory: string,
 ) => {
   const nextConfigContents = `
 import path from 'path';
 const emailsDirRelativePath = path.normalize('${emailsDirRelativePath}');
 const userProjectLocation = '${process.cwd().replace(/\\/g, '/')}';
-const previewServerLocation = '${builtPreviewAppPath.replace(/\\/g, '/')}';
+const previewServerLocation = '${appPath.replace(/\\/g, '/')}';
+const rootDirectory = '${rootDirectory.replace(/\\/g, '/')}';
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   env: {
@@ -33,7 +36,10 @@ const nextConfig = {
     PREVIEW_SERVER_LOCATION: previewServerLocation,
     USER_PROJECT_LOCATION: userProjectLocation
   },
-  outputFileTracingRoot: previewServerLocation,
+  turbopack: {
+    root: rootDirectory,
+  },
+  outputFileTracingRoot: rootDirectory,
   serverExternalPackages: ['esbuild'],
   typescript: {
     ignoreBuildErrors: true
@@ -44,7 +50,7 @@ const nextConfig = {
 export default nextConfig`;
 
   await fs.promises.writeFile(
-    path.resolve(builtPreviewAppPath, './next.config.mjs'),
+    path.resolve(appPath, './next.config.mjs'),
     nextConfigContents,
     'utf8',
   );
@@ -84,7 +90,7 @@ const getEmailSlugsFromEmailDirectory = (
 // after build
 const forceSSGForEmailPreviews = async (
   emailsDirPath: string,
-  builtPreviewAppPath: string,
+  appPath: string,
 ) => {
   const emailDirectoryMetadata = (await getEmailsDirectoryMetadata(
     emailsDirPath,
@@ -104,15 +110,13 @@ const forceSSGForEmailPreviews = async (
       'utf8',
     );
   };
+  await removeForceDynamic(path.resolve(appPath, './src/app/layout.tsx'));
   await removeForceDynamic(
-    path.resolve(builtPreviewAppPath, './src/app/layout.tsx'),
-  );
-  await removeForceDynamic(
-    path.resolve(builtPreviewAppPath, './src/app/preview/[...slug]/page.tsx'),
+    path.resolve(appPath, './src/app/preview/[...slug]/page.tsx'),
   );
 
   await fs.promises.appendFile(
-    path.resolve(builtPreviewAppPath, './src/app/preview/[...slug]/page.tsx'),
+    path.resolve(appPath, './src/app/preview/[...slug]/page.tsx'),
     `
 
 export function generateStaticParams() { 
@@ -124,8 +128,8 @@ export function generateStaticParams() {
   );
 };
 
-const updatePackageJson = async (builtPreviewAppPath: string) => {
-  const packageJsonPath = path.resolve(builtPreviewAppPath, './package.json');
+const updatePackageJson = async (appPath: string) => {
+  const packageJsonPath = path.resolve(appPath, './package.json');
   const packageJson = JSON.parse(
     await fs.promises.readFile(packageJsonPath, 'utf8'),
   ) as {
@@ -134,22 +138,11 @@ const updatePackageJson = async (builtPreviewAppPath: string) => {
     dependencies: Record<string, string>;
     devDependencies: Record<string, string>;
   };
-  // Turbopack has some errors with the imports in @react-email/tailwind
   packageJson.scripts.build =
     'cross-env NODE_OPTIONS="--experimental-vm-modules --disable-warning=ExperimentalWarning" next build';
   packageJson.scripts.start =
     'cross-env NODE_OPTIONS="--experimental-vm-modules --disable-warning=ExperimentalWarning" next start';
-  delete packageJson.scripts.postbuild;
-
-  packageJson.name = 'preview-server';
 
-  for (const [dependency, version] of Object.entries(
-    packageJson.devDependencies,
-  )) {
-    packageJson.devDependencies[dependency] = version.replace('workspace:', '');
-  }
-
-  delete packageJson.devDependencies['@react-email/components'];
   delete packageJson.scripts.prepare;
 
   await fs.promises.writeFile(
@@ -165,6 +158,7 @@ export const build = async ({
 }: Args) => {
   try {
     const previewServerLocation = await getPreviewServerLocation();
+    const { rootDir: rootDirectory } = await getPackages(process.cwd());
 
     const spinner = ora({
       text: 'Starting build process...',
@@ -174,6 +168,10 @@ export const build = async ({
 
     spinner.text = `Checking if ${emailsDirRelativePath} folder exists`;
     if (!fs.existsSync(emailsDirRelativePath)) {
+      spinner.stopAndPersist({
+        symbol: logSymbols.error,
+        text: `Directory does not exist: ${emailsDirRelativePath}`,
+      });
       process.exit(1);
     }
 
@@ -187,20 +185,32 @@ export const build = async ({
       await fs.promises.rm(builtPreviewAppPath, { recursive: true });
     }
 
-    spinner.text = 'Copying preview app from CLI to `.react-email`';
+    spinner.text = 'Copying UI source to `.react-email`';
     await fs.promises.cp(previewServerLocation, builtPreviewAppPath, {
       recursive: true,
       filter: (source: string) => {
-        // do not copy the CLI files
+        const relativeSource = path.relative(previewServerLocation, source);
         return (
-          !/(\/|\\)cli(\/|\\)?/.test(source) &&
-          !/(\/|\\)\.next(\/|\\)?/.test(source) &&
-          !/(\/|\\)\.turbo(\/|\\)?/.test(source) &&
-          !/(\/|\\)node_modules(\/|\\)?$/.test(source)
+          !/\.next/.test(relativeSource) &&
+          !/\.turbo/.test(relativeSource) &&
+          !/node_modules\/.bin/.test(relativeSource)
         );
       },
     });
 
+    await fs.promises.cp(
+      path.resolve(previewServerLocation, 'node_modules/.bin'),
+      path.resolve(builtPreviewAppPath, 'node_modules/.bin'),
+      {
+        recursive: true,
+        // With this enabled, means the symlinks remain relative, which is
+        // what we want for copying it over. If we don't enable this,
+        // it resolves the symlink to the original location on disk,
+        // which ends up causing unexpected errors.
+        verbatimSymlinks: true,
+      },
+    );
+
     if (fs.existsSync(staticPath)) {
       spinner.text =
         'Copying `static` folder into `.react-email/public/static`';
@@ -218,6 +228,7 @@ export const build = async ({
     await setNextEnvironmentVariablesForBuild(
       emailsDirRelativePath,
       builtPreviewAppPath,
+      rootDirectory,
     );
 
     spinner.text = 'Setting server side generation for the email preview pages';
@@ -226,13 +237,6 @@ export const build = async ({
     spinner.text = "Updating package.json's build and start scripts";
     await updatePackageJson(builtPreviewAppPath);
 
-    spinner.text = 'Installing dependencies on `.react-email`';
-    await installDependencies({
-      cwd: builtPreviewAppPath,
-      silent: true,
-      packageManager,
-    });
-
     spinner.stopAndPersist({
       text: 'Successfully prepared `.react-email` for `next build`',
       symbol: logSymbols.success,

packages/react-email/src/utils/.gitignore

@@ -0,0 +1 @@
+.test

packages/react-email/src/utils/get-preview-server-location.spec.ts

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { installPreviewServer } from './get-preview-server-location.js';
+import { packageJson } from './packageJson.js';
+
+test.sequential('installPreviewServer()', { timeout: 60_000 }, async () => {
+  const testDirectory = path.join(import.meta.dirname, '.test');
+  await installPreviewServer(testDirectory, packageJson.version);
+  expect(fs.existsSync(testDirectory)).toBe(true);
+
+  const importedModule = await import(path.join(testDirectory, 'index.mjs'));
+  expect({ ...importedModule }).toEqual({
+    version: packageJson.version,
+  });
+  await fs.promises.rm(testDirectory, { recursive: true, force: true });
+});