Ensure Next.js outputs static exports at build time (#69)

mars · web-flow · commit e3aee408b97b · 2026-02-13T07:04:12.000-08:00
* Ensure Next.js outputs static exports at build time

* Revise error message to describe alternative heroku/nodejs configuration.

* Update static-web-server config: runtime config globs all HTML files, use Next's 404 page, enable clean URLs, and augment the integration test.
diff --git a/buildpacks/website-nextjs/README.md b/buildpacks/website-nextjs/README.md
@@ -3,7 +3,7 @@
 * At build:
   * Detects `next` in the app's `package.json` dependencies.
   * Requires `heroku/nodejs` installation and build.
-  * Configures `heroku/static-web-server` for `next`'s output.
+  * Configures `heroku/static-web-server` for `next`'s default output to `out/`.
 
 ## Usage
 
@@ -13,6 +13,14 @@ Create an app with [Next.js](https://nextjs.org/):
 npx create-next-app@latest
 ```
 
+Configure the Next.js app to for [static exports](https://nextjs.org/docs/app/guides/static-exports). Set the output mode in `next.config.js`:
+
+```javascript
+const nextConfig = {
+  output: 'export'
+}
+```
+
 Now, the app should be ready to build, with Next.js auto-detected by `heroku/builder`:
 
 ```bash
diff --git a/buildpacks/website-nextjs/src/errors.rs b/buildpacks/website-nextjs/src/errors.rs
@@ -14,7 +14,10 @@ locally with a minimal example and open an issue in the buildpack's GitHub repos
 #[derive(Debug)]
 pub(crate) enum WebsiteNextjsBuildpackError {
     Detect(io::Error),
+    NextInfoCommandError(io::Error),
+    NextInfoFailure(String),
     ReadPackageJson(io::Error),
+    RequiresStaticExport,
     ParsePackageJson(serde_json::Error),
     SettingBuildPlanMetadata(toml::ser::Error),
 }
@@ -58,13 +61,48 @@ fn buildpack_error_message(error: WebsiteNextjsBuildpackError) -> ErrorMessage {
             error_string: e.to_string(),
             error_id: "detect_error".to_string(),
         },
+        WebsiteNextjsBuildpackError::NextInfoCommandError(e) => ErrorMessage {
+            message: formatdoc! {"
+                Error executing `next info` in {buildpack_name}.
+            ", buildpack_name = style::value(BUILDPACK_NAME) },
+            error_string: e.to_string(),
+            error_id: "next_info_command_error".to_string(),
+        },
+        WebsiteNextjsBuildpackError::NextInfoFailure(m) => ErrorMessage {
+            message: formatdoc! {"
+                `next info` command failed in {buildpack_name}.
+            ", buildpack_name = style::value(BUILDPACK_NAME) },
+            error_string: m,
+            error_id: "next_info_failure".to_string(),
+        },
         WebsiteNextjsBuildpackError::ReadPackageJson(e) => ErrorMessage {
             message: formatdoc! {"
                 Error reading package.json from {buildpack_name}.
             ", buildpack_name = style::value(BUILDPACK_NAME) },
             error_string: e.to_string(),
             error_id: "read_package_json_error".to_string(),
         },
+        WebsiteNextjsBuildpackError::RequiresStaticExport => ErrorMessage {
+            message: formatdoc! {r#"
+                {buildpack_name} requires `output: 'export'` set in `next.config.js`.
+
+                This buildpack deploys Next.js as a static website, for enhanced
+                performance and security. Some features of Next.js are not supported
+                in static mode. More info at:
+                
+                https://nextjs.org/docs/app/guides/static-exports
+
+                You may choose to build a Node.js app, instead of `output: 'export'`.
+                Set or replace the buildpacks in the `project.toml` file, and then
+                retry the build:
+
+                    [[io.buildpacks.group]]
+                    id = "heroku/nodejs"
+
+            "#, buildpack_name = style::value(BUILDPACK_NAME) },
+            error_string: "Next.js build output must target static exports".to_string(),
+            error_id: "requires_static_export_error".to_string(),
+        },
         WebsiteNextjsBuildpackError::ParsePackageJson(e) => ErrorMessage {
             message: formatdoc! {"
                 Error parsing package.json from {buildpack_name}.
diff --git a/buildpacks/website-nextjs/src/main.rs b/buildpacks/website-nextjs/src/main.rs
@@ -1,6 +1,8 @@
 mod errors;
 mod o11y;
 
+use std::process::Command;
+
 use crate::errors::{on_error, WebsiteNextjsBuildpackError};
 use crate::o11y::*;
 use libcnb::build::{BuildContext, BuildResult, BuildResultBuilder};
@@ -56,14 +58,21 @@ impl Buildpack for WebsiteNextjsBuildpack {
 
         let mut static_web_server_req = Require::new("static-web-server");
 
+        // Following Next.js static deployment guidance
+        // https://nextjs.org/docs/app/guides/static-exports
         static_web_server_req
             .metadata(toml! {
                 root = "/workspace/out"
                 index = "index.html"
 
+                [runtime_config]
+                html_files = ["**/*.html"]
+
                 [errors.404]
-                file_path = "_not-found.html"
-                status = 404
+                file_path = "404.html"
+
+                [caddy_server_opts]
+                clean_urls = true
             })
             .map_err(WebsiteNextjsBuildpackError::SettingBuildPlanMetadata)?;
 
@@ -90,6 +99,27 @@ impl Buildpack for WebsiteNextjsBuildpack {
 
     fn build(&self, _context: BuildContext<Self>) -> libcnb::Result<BuildResult, Self::Error> {
         log_header(BUILDPACK_NAME);
+
+        // Ensure comptibility with the static web server,
+        // that Next's build output is set to static exports.
+        let mut cmd = Command::new("sh");
+        cmd.args(["-c", "npm exec next info"]);
+        let next_info = cmd
+            .output()
+            .map_err(WebsiteNextjsBuildpackError::NextInfoCommandError)?;
+        let next_info_stdout = String::from_utf8_lossy(&next_info.stdout);
+        let next_info_stderr = String::from_utf8_lossy(&next_info.stderr);
+        if !next_info.status.success() {
+            return Err(libcnb::Error::BuildpackError(
+                WebsiteNextjsBuildpackError::NextInfoFailure(next_info_stderr.to_string()),
+            ));
+        }
+        if !next_info_stdout.contains(&"output: export".to_string()) {
+            return Err(libcnb::Error::BuildpackError(
+                WebsiteNextjsBuildpackError::RequiresStaticExport,
+            ));
+        }
+
         BuildResultBuilder::new().build()
     }
 
diff --git a/buildpacks/website-nextjs/tests/fixtures/next_app/app/nested/page.tsx b/buildpacks/website-nextjs/tests/fixtures/next_app/app/nested/page.tsx
@@ -0,0 +1,48 @@
+import Image from "next/image";
+
+export default function Home() {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-zinc-50 font-sans dark:bg-black">
+      <main className="flex min-h-screen w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start">
+        <Image
+          className="dark:invert"
+          src="/next.svg"
+          alt="Next.js logo"
+          width={100}
+          height={20}
+          priority
+        />
+        <div className="flex flex-col items-center gap-6 text-center sm:items-start sm:text-left">
+          <h1 className="max-w-xs text-3xl font-semibold leading-10 tracking-tight text-black dark:text-zinc-50">
+            A Nested Page
+          </h1>
+        </div>
+        <div className="flex flex-col gap-4 text-base font-medium sm:flex-row">
+          <a
+            className="flex h-12 w-full items-center justify-center gap-2 rounded-full bg-foreground px-5 text-background transition-colors hover:bg-[#383838] dark:hover:bg-[#ccc] md:w-[158px]"
+            href="https://vercel.com/new?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            <Image
+              className="dark:invert"
+              src="/vercel.svg"
+              alt="Vercel logomark"
+              width={16}
+              height={16}
+            />
+            Deploy Now
+          </a>
+          <a
+            className="flex h-12 w-full items-center justify-center rounded-full border border-solid border-black/[.08] px-5 transition-colors hover:border-transparent hover:bg-black/[.04] dark:border-white/[.145] dark:hover:bg-[#1a1a1a] md:w-[158px]"
+            href="https://nextjs.org/docs?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Documentation
+          </a>
+        </div>
+      </main>
+    </div>
+  );
+}
diff --git a/buildpacks/website-nextjs/tests/integration_test.rs b/buildpacks/website-nextjs/tests/integration_test.rs
@@ -24,8 +24,34 @@ fn nextjs_app() {
                 })
                 .unwrap();
                 let response_body = response.into_string().unwrap();
+                assert_contains!(response_body, "Generated by create next app");
+                assert_contains!(response_body, "To get started");
 
-                assert_contains!(response_body, "Create Next App");
+                let second_response = retry(DEFAULT_RETRIES, DEFAULT_RETRY_DELAY, || {
+                    ureq::get(&format!("http://{socket_addr}/nested")).call()
+                })
+                .unwrap();
+                let second_response_body = second_response.into_string().unwrap();
+                assert_contains!(response_body, "Generated by create next app");
+                assert_contains!(second_response_body, "A Nested Page");
+
+                let not_found_result = retry(DEFAULT_RETRIES, DEFAULT_RETRY_DELAY, || {
+                    ureq::get(&format!("http://{socket_addr}/non-existent-path")).call()
+                });
+                match not_found_result {
+                    Err(ureq::Error::Status(code, response)) => {
+                        assert_eq!(code, 404);
+                        let response_body = response.into_string().unwrap();
+                        assert_contains!(response_body, "Generated by create next app");
+                        assert_contains!(response_body, "This page could not be found.");
+                    }
+                    Ok(_) => {
+                        panic!("should respond 404 Not Found, but got 200 ok");
+                    }
+                    Err(error) => {
+                        panic!("should respond 404 Not Found, but got other error: {error:?}");
+                    }
+                }
             },
         );
     });
