Using ClojureScript’s :target :es6 for Native ES‑Module Integration

Problem: Mixing ClojureScript with modern JavaScript tooling

When a ClojureScript project grows, developers often need to share code with plain JavaScript modules, use Webpack or Rollup for tree‑shaking, or run the code in Node.js that expects native ES‑modules. The default ClojureScript compiler output is a single goog.require‑based bundle, which does not play nicely with these tools.

How :target :es6 works

• Compiler flag: :target :es6 tells the compiler to emit each namespace as an independent ES‑module.
• Exporting vars: Only vars marked with ^:export become public exports. All other vars stay private to the module.
• Dependencies: The compiler generates import statements for goog.require dependencies, so the module can use other ClojureScript namespaces or JavaScript modules.
• Compatibility: The output can be consumed by browsers with type="module", Node.js (v14+ with type=module or --experimental-modules), or any bundler that understands ES‑modules.

Concrete Example

1. Create a simple namespace – src/myapp/core.cljs:

   (ns myapp.core
     (:require [clojure.string :as str]))
   
   ;; Exported function
   (defn ^:export greet [name]
     (str "Hello, " name "!"))
   
   ;; Internal helper – not exported
   (defn internal-hello [name]
     (str "Hi, " name))
   

2. Compile with :target :es6 – in project.clj or shadow-cljs.edn:

   :compiler {
     :target :es6
     :optimizations :simple
   }
   

   Run lein cljsbuild once or shadow-cljs release core to produce core.js.

3. Check the generated file – the first few lines look like:

   import * as str from "clojure.string.js";
   export function greet(name) {
     return str.concat("Hello, ", name, "!");
   }
   // internal-hello is not exported
   

   Notice the export function greet and the import of clojure.string.js.

4. Test in Node.js – create test.js:

   import { greet } from "./core.js";
   console.log(greet("World")); // → Hello, World!
   

   Run with node --experimental-modules test.js or node test.js if your package.json has "type": "module". The output should be exactly Hello, World!.

5. Bundle with Rollup – rollup.config.js:

   export default {
     input: "core.js",
     output: { file: "bundle.js", format: "esm" },
     plugins: [
       // Rollup will tree‑shake unused exports
     ]
   };
   

   Running Rollup will produce bundle.js that contains only the exported greet function.

Trade‑offs and Limitations

• Advanced optimizations: When :optimizations :advanced is used, exported names are mangled unless you provide externs. Add an extern file that lists the exported vars to preserve their names.
• Bundle size: Using :target :es6 with :optimizations :simple can lead to larger bundles because dead‑code elimination is less aggressive than with :advanced.
• Interop with CommonJS: Native ES‑modules cannot be required via require() in a CommonJS context without a loader or transpilation step.
• Metadata requirement: Every var you want to expose must be annotated with ^:export. Forgetting this will result in the var being private and potentially removed during optimization.

Actionable Closing

1. Set :target :es6 in your compiler config and add ^:export metadata to public vars.
2. Compile and inspect the output for export statements.
3. If you plan to use :advanced, create an extern file listing the exported names.
4. Integrate the generated JS with Webpack, Rollup, or Node.js by importing the module. Verify by running a small test script.
5. Use tree‑shaking in your bundler to keep the bundle lean – only the exported functions you actually import will survive.

By emitting native ES6 modules, ClojureScript projects can seamlessly share code with the broader JavaScript ecosystem, leverage modern bundlers’ optimizations, and keep encapsulation intact.