support eject to fully customize next folder

.changeset/many-knives-warn.md

@@ -0,0 +1,6 @@
+---
+"create-llama": patch
+"@llamaindex/server": patch
+---
+
+support eject to fully customize next folder

eslint.config.mjs

@@ -58,6 +58,8 @@ export default tseslint.config(
       "**/node_modules/**",
       "**/build/**",
       "packages/server/server/**",
+      "packages/server/project/**",
+      "packages/server/bin/**",
     ],
   },
 );

packages/create-llama/e2e/shared/llamaindexserver_template.spec.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "@playwright/test";
-import { ChildProcess } from "child_process";
+import { ChildProcess, execSync } from "child_process";
 import fs from "fs";
 import path from "path";
 import type {
@@ -28,6 +28,7 @@ const templateUseCases = [
   "deep_research",
   "code_generator",
 ];
+const ejectDir = "next";
 
 for (const useCase of templateUseCases) {
   test.describe(`Test use case ${useCase} ${templateFramework} ${dataSource} ${templateUI} ${appType} ${templatePostInstallAction}`, async () => {
@@ -110,6 +111,28 @@ for (const useCase of templateUseCases) {
       expect(response.ok()).toBeTruthy();
     });
 
+    test("Should successfully eject, install dependencies and build without errors", async () => {
+      test.skip(
+        templateFramework !== "nextjs" ||
+          useCase !== "code_generator" ||
+          dataSource === "--llamacloud",
+        "Eject test only applies to Next.js framework, code generator use case, and non-llamacloud",
+      );
+
+      // Run eject command
+      execSync("npm run eject", { cwd: path.join(cwd, name) });
+
+      // Verify next directory exists
+      const nextDirExists = fs.existsSync(path.join(cwd, name, ejectDir));
+      expect(nextDirExists).toBeTruthy();
+
+      // Install dependencies in next directory
+      execSync("npm install", { cwd: path.join(cwd, name, ejectDir) });
+
+      // Run build
+      execSync("npm run build", { cwd: path.join(cwd, name, ejectDir) });
+    });
+
     // clean processes
     test.afterAll(async () => {
       appProcess?.kill();

packages/create-llama/templates/components/use-cases/typescript/agentic_rag/README-template.md

@@ -41,6 +41,14 @@ curl --location 'localhost:3000/api/chat' \
 --data '{ "messages": [{ "role": "user", "content": "What standards for a letter exist?" }] }'
 ```
 
+## Eject Mode
+
+If you want to fully customize the server UI and routes, you can use `npm eject`. It will create a normal Next.js project with the same functionality as @llamaindex/server.
+
+```bash
+npm run eject
+```
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

packages/create-llama/templates/components/use-cases/typescript/code_generator/README-template.md

@@ -42,6 +42,14 @@ curl --location 'localhost:3000/api/chat' \
 --data '{ "messages": [{ "role": "user", "content": "Compare the financial performance of Apple and Tesla" }] }'
 ```
 
+## Eject Mode
+
+If you want to fully customize the server UI and routes, you can use `npm eject`. It will create a normal Next.js project with the same functionality as @llamaindex/server.
+
+```bash
+npm run eject
+```
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

packages/create-llama/templates/components/use-cases/typescript/deep_research/README-template.md

@@ -53,6 +53,14 @@ curl --location 'localhost:3000/api/chat' \
 --data '{ "messages": [{ "role": "user", "content": "Compare the financial performance of Apple and Tesla" }] }'
 ```
 
+## Eject Mode
+
+If you want to fully customize the server UI and routes, you can use `npm eject`. It will create a normal Next.js project with the same functionality as @llamaindex/server.
+
+```bash
+npm run eject
+```
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

packages/create-llama/templates/components/use-cases/typescript/document_generator/README-template.md

@@ -42,6 +42,14 @@ curl --location 'localhost:3000/api/chat' \
 --data '{ "messages": [{ "role": "user", "content": "Compare the financial performance of Apple and Tesla" }] }'
 ```
 
+## Eject Mode
+
+If you want to fully customize the server UI and routes, you can use `npm eject`. It will create a normal Next.js project with the same functionality as @llamaindex/server.
+
+```bash
+npm run eject
+```
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

packages/create-llama/templates/components/use-cases/typescript/financial_report/README-template.md

@@ -41,6 +41,14 @@ curl --location 'localhost:3000/api/chat' \
 --data '{ "messages": [{ "role": "user", "content": "Generate a financial report that compares the financial performance of Apple and Tesla" }] }'
 ```
 
+## Eject Mode
+
+If you want to fully customize the server UI and routes, you can use `npm eject`. It will create a normal Next.js project with the same functionality as @llamaindex/server.
+
+```bash
+npm run eject
+```
+
 ## Learn More
 
 To learn more about LlamaIndex, take a look at the following resources:

packages/create-llama/templates/components/vectordbs/llamaindexserver/llamacloud/typescript/generate.ts

@@ -1,8 +1,9 @@
+import { OpenAI } from "@llamaindex/openai";
 import { generateEventComponent } from "@llamaindex/server";
 import * as dotenv from "dotenv";
 import "dotenv/config";
 import * as fs from "fs/promises";
-import { LLamaCloudFileService, OpenAI } from "llamaindex";
+import { LLamaCloudFileService } from "llamaindex";
 import * as path from "path";
 import { getIndex } from "./app/data";
 import { initSettings } from "./app/settings";

packages/create-llama/templates/types/llamaindexserver/nextjs/package.json

@@ -6,7 +6,8 @@
     "generate:datasource": "tsx src/generate.ts datasource",
     "generate:ui": "tsx src/generate.ts ui",
     "dev": "nodemon",
-    "start": "tsx src/index.ts"
+    "start": "tsx src/index.ts",
+    "eject": "llamaindex-server eject"
   },
   "dependencies": {
     "@llamaindex/openai": "~0.4.0",

packages/server/.gitignore

@@ -1,5 +1,8 @@
 # server contains Nextjs frontend code (not compiled)
 server/
 
+# the ejected nextjs project
+project/
+
 # temp is the copy of next folder but without API folder, used to build frontend static files
 temp/

packages/server/README.md

@@ -300,6 +300,23 @@ The server always provides a chat interface at the root path (`/`) with:
 - The server automatically mounts the `data` and `output` folders at `{server_url}{api_prefix}/files/data` (default: `/api/files/data`) and `{server_url}{api_prefix}/files/output` (default: `/api/files/output`) respectively.
 - Your workflows can use both folders to store and access files. By convention, the `data` folder is used for documents that are ingested, and the `output` folder is used for documents generated by the workflow.
 
+### Eject Mode
+
+If you want to fully customize the server UI and routes, you can use `npm eject`. It will create a normal Next.js project with the same functionality as @llamaindex/server.
+By default, the ejected project will be in the `next` directory in the current working directory. You can change the output directory by providing custom path after `eject` command:
+
+```bash
+npm eject <path-to-output-directory>
+```
+
+How eject works:
+
+1. Init nextjs project with eslint, prettier, postcss, tailwindcss, shadcn components, etc.
+2. Copy your workflow definition and setting files in src/app/\* to the ejected project in app/api/chat
+3. Copy your components, data, output, storage folders to the ejected project
+4. Copy your current .env file to the ejected project
+5. Clean up files that are no longer needed and update imports
+
 ## API Reference
 
 - [LlamaIndexServer](https://ts.llamaindex.ai/docs/api/classes/LlamaIndexServer)

packages/server/bin/eject.cjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+const fs = require("fs").promises;
+const path = require("path");
+
+// Resolve the project directory in node_modules/@llamaindex/server/project
+// This is the template that used to construct the nextjs project
+const projectDir = path.resolve(__dirname, "../project");
+
+// Resolve the src directory that contains workflow & setting files
+const srcDir = path.join(process.cwd(), "src");
+const srcAppDir = path.join(srcDir, "app");
+const generateFile = path.join(srcDir, "generate.ts");
+const envFile = path.join(process.cwd(), ".env");
+
+// The environment variables that are used as LlamaIndexServer configs
+const SERVER_CONFIG_VARS = [
+  {
+    key: "OPENAI_API_KEY",
+    defaultValue: "<your-openai-api-key>",
+    description: "OpenAI API key",
+  },
+  {
+    key: "SUGGEST_NEXT_QUESTIONS",
+    defaultValue: "true",
+    description: "Whether to suggest next questions (`suggestNextQuestions`)",
+  },
+  {
+    key: "COMPONENTS_DIR",
+    defaultValue: "components",
+    description: "Directory for custom components (`componentsDir`)",
+  },
+  {
+    key: "WORKFLOW_FILE_PATH",
+    defaultValue: "app/api/chat/app/workflow.ts",
+    description: "The path to the workflow file (will be updated in dev mode)",
+  },
+  {
+    key: "NEXT_PUBLIC_USE_COMPONENTS_DIR",
+    defaultValue: "true",
+    description: "Whether to enable components directory feature on frontend",
+  },
+  {
+    key: "NEXT_PUBLIC_DEV_MODE",
+    defaultValue: "true",
+    description: "Whether to enable dev mode (`devMode`)",
+  },
+  {
+    key: "NEXT_PUBLIC_STARTER_QUESTIONS",
+    defaultValue: '["Summarize the document", "What are the key points?"]',
+    description:
+      "Initial questions to display in the chat (`starterQuestions`)",
+  },
+  {
+    key: "NEXT_PUBLIC_SHOW_LLAMACLOUD_SELECTOR",
+    defaultValue: "false",
+    description:
+      "Whether to show LlamaCloud selector for frontend (`llamaCloudIndexSelector`)",
+  },
+];
+
+async function eject() {
+  try {
+    // validate required directories (nextjs project template, src directory, src/app directory)
+    const requiredDirs = [projectDir, srcDir, srcAppDir];
+    for (const dir of requiredDirs) {
+      const exists = await fs
+        .access(dir)
+        .then(() => true)
+        .catch(() => false);
+      if (!exists) {
+        console.error("Error: directory does not exist at", dir);
+        process.exit(1);
+      }
+    }
+
+    // Get destination directory from command line arguments (pnpm eject <path>)
+    const args = process.argv;
+    const outputIndex = args.indexOf("eject");
+    const destDir =
+      outputIndex !== -1 && args[outputIndex + 1]
+        ? path.resolve(args[outputIndex + 1]) // Use provided path after eject
+        : path.join(process.cwd(), "next"); // Default to "next" folder in the current working directory
+
+    // remove destination directory if it exists
+    await fs.rm(destDir, { recursive: true, force: true });
+
+    // create destination directory
+    await fs.mkdir(destDir, { recursive: true });
+
+    // Copy the nextjs project template to the destination directory
+    await fs.cp(projectDir, destDir, { recursive: true });
+
+    // copy src/app/* to destDir/app/api/chat
+    const chatRouteDir = path.join(destDir, "app", "api", "chat");
+    await fs.cp(srcAppDir, path.join(chatRouteDir, "app"), { recursive: true });
+
+    // nextjs project doesn't depend on @llamaindex/server anymore, we need to update the imports in workflow file
+    const workflowFile = path.join(chatRouteDir, "app", "workflow.ts");
+    let workflowContent = await fs.readFile(workflowFile, "utf-8");
+    workflowContent = workflowContent.replace("@llamaindex/server", "../utils");
+    await fs.writeFile(workflowFile, workflowContent);
+
+    // copy generate.ts if it exists
+    const genFilePath = path.join(chatRouteDir, "generate.ts");
+    const genFileExists = await copy(generateFile, genFilePath);
+    if (genFileExists) {
+      // update the import @llamaindex/server in generate.ts
+      let genContent = await fs.readFile(genFilePath, "utf-8");
+      genContent = genContent.replace("@llamaindex/server", "./utils");
+      await fs.writeFile(genFilePath, genContent);
+    }
+
+    // copy folders in root directory if exists
+    const rootFolders = ["components", "data", "output", "storage"];
+    for (const folder of rootFolders) {
+      await copy(path.join(process.cwd(), folder), path.join(destDir, folder));
+    }
+
+    // copy .env if it exists or create a new one
+    const envFileExists = await copy(envFile, path.join(destDir, ".env"));
+    if (!envFileExists) {
+      await fs.writeFile(path.join(destDir, ".env"), "");
+    }
+
+    // update .env file with more server configs
+    let envFileContent = await fs.readFile(path.join(destDir, ".env"), "utf-8");
+    for (const envVar of SERVER_CONFIG_VARS) {
+      const { key, defaultValue, description } = envVar;
+      if (!envFileContent.includes(key)) {
+        // if the key is not exists in the env file, add it
+        envFileContent += `\n# ${description}\n${key}=${defaultValue}\n`;
+      }
+    }
+    await fs.writeFile(path.join(destDir, ".env"), envFileContent);
+
+    // rename gitignore -> .gitignore
+    await fs.rename(
+      path.join(destDir, "gitignore"),
+      path.join(destDir, ".gitignore"),
+    );
+
+    // user can customize layout directory in nextjs project, remove layout api
+    await fs.rm(path.join(destDir, "app", "api", "layout"), {
+      recursive: true,
+      force: true,
+    });
+
+    // remove no-needed files
+    await fs.unlink(path.join(destDir, "public", "config.js"));
+    await fs.unlink(path.join(destDir, "next-build.config.ts"));
+
+    console.log("Successfully ejected @llamaindex/server to", destDir);
+  } catch (error) {
+    console.error("Error during eject:", error.message);
+    process.exit(1);
+  }
+}
+
+// copy src to dest if src exists, return true if src exists
+async function copy(src, dest) {
+  const srcExists = await fs
+    .access(src)
+    .then(() => true)
+    .catch(() => false);
+  if (srcExists) {
+    await fs.cp(src, dest, { recursive: true });
+  }
+  return srcExists;
+}
+
+eject();