Deploying Next.js to Databricks Apps: A Guide to Standalone Node.js Hosting

Databricks has evolved far beyond just Spark notebooks. With the introduction of Databricks Apps, developers can now host full-stack applications directly within the Databricks ecosystem, leveraging built-in security and integration with Unity Catalog.

While the documentation heavily favors Python, the Databricks App Runtime is a robust Ubuntu 22.04 LTS environment that comes pre-installed with Node.js v22.16. However, if you look at the official Databricks documentation, you’ll find a gap: while there is guidance on Node.js development, there is virtually zero documentation on deploying a modern framework like Next.js.

The Challenge: Next.js on Databricks

Next.js is the gold standard for React frameworks, but its default build process isn’t optimized for the specific way Databricks Apps handles deployments. Because Databricks tries to manage your dependencies automatically, a standard npm run build can lead to bloated deployments or runtime conflicts.

The Solution: Next.js Standalone Mode

To get Next.js running smoothly on Databricks, we leverage Standalone Mode. This feature tells Next.js to output a minimal set of files including only the necessary dependencies to run the application, significantly reducing the bundle size.

1. Configure Next.js

In your next.config.ts (or .js), enable the standalone output:

const nextConfig = { output: 'standalone', }; export default nextConfig;

2. Optimize the Databricks Asset Bundle (DAB)

The secret to a successful deployment lies in how you define your Databricks Asset Bundle and handle the package.json file.

The “Hidden” Logic of Databricks Runtimes: According to the official deployment documentation, Databricks follows a specific execution flow:

If package.json is present, the runtime automatically runs npm install and npm run build.

The Hack: To avoid redundant installs and build steps (since we want to use our pre-built standalone folder), we remove package.json from the final asset bundle. This forces the runtime to skip the install phase and execute our custom start command immediately.

3. Configuration Files

In your app.yaml, point the command directly to the standalone entry point:

command: [ "node", "server.js" ]

In your databricks.yml, ensure the path for your artifact points to the .next/standalone directory created after your local build.

Backend Authentication: Bridging Next.js and Databricks APIs

If your Next.js app needs to communicate with a backend also hosted on Databricks Apps (or any Databricks Service), you can leverage the auto-injected environment variables.

Databricks Apps automatically provides:

• DATABRICKS_CLIENT_ID
• DATABRICKS_CLIENT_SECRET
• DATABRICKS_HOST

Implementation: Middleware Proxy

Instead of using rewrites in next.config.ts (which can be rigid), create a middleware.ts or a proxy handler. This allows you to programmatically generate a Databricks Workspace-scoped API token and inject it into the headers of your backend requests.

Why avoid next.config.ts rewrites? Rewrites happen at the routing level, making it difficult to inject dynamic auth tokens generated at runtime using the DATABRICKS_CLIENT_SECRET. Using a middleware approach ensures every request to your backend is authenticated correctly using the app’s service principal identity.

Note: You can verify these variables by opening your App in the Databricks Workspace and navigating to the Environment tab.

Summary Checklist for Deployment

1. Run next build locally or in your CI/CD pipeline.
2. Navigate to .next/standalone.
3. Delete the package.json inside that folder (to prevent Databricks from re-installing).
4. Ensure app.yaml is set to node server.js.
5. Deploy the bundle using databricks bundle deploy.
6. Deploy the app using databricks bundle start <your frontend app>

By following this pattern, you bypass the “opinionated” Node.js setup of Databricks and gain a high-performance, minimal-footprint Next.js application running natively in your data lakehouse.

A quick note about this approach is that the deployment inside the app instance takes around 5-10 minutes or even longer depending on the number of packages in node_modules folder. The reason is that Databricks runtime copies all files in the standalone from the bundle folder inside the workspace to the target folder in the instance. I hope Databricks team will provider a faster way to deploy such as zipping the frontend build folder rather than copying raw files.