Resolving the "use client" Directive Issue in Turborepo with tsup

While working on a Turborepo monorepo structure, I encountered a peculiar issue related to the "use client" directive while bundling TypeScript libraries using tsup. Here, I’ll detail the problem, my troubleshooting process, and the solution I implemented, emphasizing considerations relevant to frontend engineering.

---

The Problem

While building a packages/ui library using tsup, the following error occurred during the web:build process:

web:build: ../../packages/ui/dist/chart/index.js
web:build: Error:
web:build:   x The "use client" directive must be placed before other expressions. Move it to the top of the file to resolve this issue.
web:build:    ,-[/app/packages/ui/dist/chart/index.js:1:1]
web:build:  1 | "use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";

Examining the built output confirmed that "use strict" was being placed before "use client," causing the error. This violated the requirement that "use client" must appear as the very first statement in a file.

Initial Debugging Steps

To address the issue, I attempted to use tsup's banner option, which allows prepending custom content to the output files. My configuration looked like this:

esbuildOptions: (options) => {
  options.banner = {
    js: '"use client";',
  };
},

Despite this configuration, the error persisted. Upon further inspection, it became clear that the banner was not being placed at the very beginning of the file—instead, it appeared after the automatically added "use strict" directive.

This issue seemed to be isolated to CommonJS (CJS) builds. The ESM builds did not exhibit this behavior, but due to time constraints, I decided to address the issue for CJS first.

---

Key Findings

1. Tree-Shaking Concerns: During troubleshooting, I discovered that one of the critical dependencies imported using next/dynamic did not provide an ESM build. This meant tree-shaking was ineffective, potentially leading to larger bundle sizes.
2. Immediate Workaround Needed: Since build and deployment timelines could not be postponed, a quick and reliable fix was necessary.

---

The Solution

I decided to manually prepend the "use client" directive for CJS builds. Here's how I implemented the solution:

Updated Build Script

Instead of relying on tsup's banner option, I added a post-processing script to ensure the directive was correctly placed:

"scripts": {
  "build": "tsup && tsc && node ./post-script.js"
},

Post-Script Implementation

The post-script.js script reads the output CJS files, modifies them to ensure "use client" is the first statement, and writes the changes back.

Updated Package Exports

"exports": {
  ".": {
    "types": "./dist/src/index.d.ts",
    "require": "./dist/index.js",
    "import": "./dist/index.mjs"
  }
}

---

Reflection and Lessons Learned

Strengths of the Solution

1. Quick Resolution: The post-script ensured a reliable fix without extensive rework of the build process.
2. CJS and ESM Compatibility: By supporting both module types, the library remains versatile for a wide range of consumers.
3. Minimized Disruption: The fix allowed the project to proceed without delaying deployment timelines.

Areas for Improvement

1. Long-Term ESM Transition: Dependencies that lack ESM builds should be addressed in future iterations to enable proper tree-shaking and optimize bundle sizes.
2. Build Tool Improvements: Contributions to tsup or esbuild could help make the banner placement behavior more configurable, benefiting the broader community.

---

Conclusion

This experience reinforced the importance of understanding the nuances of modern module formats (CJS vs. ESM) and their implications for builds in frameworks like Next.js. While the solution was not perfect, it balanced immediate needs with a clear path for future improvements—a critical skill in frontend engineering.