Named and default exports

Last lesson used one kind of export: named. You put a name through the hatch, the name is part of the deal, and the importing file asks for it by that name. Most exports in most projects are named exports, and if you only ever learn this one you will be fine.

There is a second kind: the default export. A module may have at most one, and it means "this is the main thing this file is for". A file called date-formatter.js whose whole job is one function is the natural case. The syntax is export default followed by the thing: export default function labelFor(text) { ... }.

The two kinds live happily in the same file. A module can have one default and any number of named exports, which is exactly how a lot of small libraries are built: the headline tool as the default, the sharp knives as named exports beside it.

This is the difference that actually matters in practice, and it is not about syntax. A named export travels with its name: export function capitalise means every importing file writes capitalise, and if they want a different word locally they have to say so explicitly. A default export travels without one. The importing file writes import anythingIWant from "./format.js" and that is that.

Read that as a trade rather than as a convenience. Named exports give you one shared vocabulary across the whole project: search for capitalise and you find every use of it. Defaults give you freedom at each call site, and the cost is that the same function can be called label in one file, format in another and f in a third. Two years in, that cost is usually larger than the convenience, which is why plenty of teams have a rule of named exports only.

One consequence worth knowing before it bites: the name after export default is for humans and for stack traces, not for importers. Writing export default function labelFor does not oblige anybody to call it labelFor. Writing export default function () with no name at all is legal too, and it is a small act of sabotage against whoever reads the error report.

Named exports are imported inside braces: import { capitalise, DASH } from "./format.js". The braces mean "pick these names out". A default export is imported with no braces: import labelFor from "./format.js". Mixing them in one line is normal and reads default-first: import labelFor, { capitalise } from "./format.js".

To use a different local name for a named import, add as: import { capitalise as toTitleCase } from "./format.js". The same keyword works on the way out too - export { capitalise as toTitleCase } - which is how a module can publish a tidy public name for a scruffier internal one.

The single most common error in this area comes from mixing the two forms up. import { labelFor } from "./format.js" when labelFor is the DEFAULT export does not throw a helpful "wrong kind" message; you asked for a named export called labelFor and there isn't one, so you get undefined or a build error about a missing export. If an import arrives undefined and you are sure the file exports it, the braces are the first thing to check.

There is a third import form: import * as format from "./format.js". It gives you a single object with every export of that module hanging off it, so you write format.capitalise(...) instead of importing each name. It is useful when a module has many exports and you want the reader to see where each one came from.

That object is the key to a much better mental model of the whole system. A module is not a bag of loose names - it is one object of named things, and importing is picking properties off it. And the default export is not magic either: on that object it is a property called default. MDN is explicit that import labelFor from "./format.js" is shorthand for import { default as labelFor } from "./format.js".

That is the model this lesson's runnable code leans on, and it is not an approximation. Our stand-in factories return an object whose keys are the module's exports, with the main tool under the literal key default - which is exactly what the real namespace object looks like. When you destructure it you have to write const { default: labelFor } = kit, renaming as you go, for the same reason the real import syntax needs as: default is a reserved word and cannot be a variable name.

A rule of thumb that will not embarrass you: name everything, and add a default only when a file genuinely has one headline export that callers will want to rename to suit their context.

The reasons are all about the reader rather than the writer. A named export is greppable, spell-checked by your tools, and consistent across every file that uses it. It is also easier for a bundler to remove when nobody uses it - the tree shaking of lesson five works on names it can see.

The reason not to be dogmatic: whole ecosystems disagree with the rule of thumb, and you will import plenty of packages whose main entry point is a default export. Knowing both forms and being able to read either is the skill. Having an opinion about which to write is a team decision, and a small one.

Two defaults in one file. A module gets one. Writing export default twice is a syntax error and the module will not evaluate at all - which is at least a fast failure.

Assuming the file name binds the default's name. It does not. date-utils.js can export default a function called anything, and importers can call it anything else again. Nothing anywhere enforces a match.

export default { a, b, c } as a way of "exporting several things". It works, but you have just made one anonymous object export instead of three named ones: importers cannot pick out only b, and a bundler cannot drop the parts nobody uses. If you want several things, export several things.

Renaming the wrong way round. In import { capitalise as toTitleCase }, the name on the LEFT is the one the other module published, and the one on the right is what you will type locally. Getting this backwards produces an error naming an export that has never existed, which reads confusingly until you know the order.

Named exports carry their names to every importer and are imported inside braces. A default export is the module's single headline value, imported without braces and named by whoever imports it. Both can live in one file. Renaming uses as, with the source name on the left. import * as gives you the module's namespace object, on which the default sits under the key default - so a default import is shorthand for taking that one property. Prefer named exports for greppability and tree shaking; read both fluently, because the ecosystem uses both.