How to mix default and named exports in JavaScript

When working with JavaScript modules, understanding the difference between default and named exports is fundamental. The default export is designed to export a single value from a module, making it the “main” exported entity. Named exports, on the other hand, allow you to export multiple values by name, and consumers can choose which ones to import.

Consider the syntax: a default export looks like this:

export default function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

This means when you import from this module, you can pick any name to refer to the exported function.

Named exports are declared by explicitly naming each export:

export function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

export function formatCurrency(amount) {
  return '$' + amount.toFixed(2);
}

When importing named exports, the syntax requires curly braces and exact names:

import { calculateTotal, formatCurrency } from './billing.js';

Whereas default imports skip the braces:

import calculateTotal from './billing.js';

One subtlety here is that you can rename named imports using the as keyword, which isn’t available with default imports because the import name is already flexible:

import { calculateTotal as total } from './billing.js';

The choice between default and named exports reflects design intent. Default exports signal a single core functionality or object, while named exports suggest a module is a toolkit of related utilities. This distinction affects how flexible or explicit your imports become.

Another technical difference manifests at the module resolution level. A default export is a property named default on the module object, while named exports are properties with their declared names. This means when you import everything as a namespace, you explicitly see this structure:

import * as billing from './billing.js';

billing.default(...); // calls default export
billing.calculateTotal(...); // calls named export

Understanding these mechanics helps when you debug import issues or when interfacing with tools that consume module metadata. It also clarifies why mixing default and named exports in a single module can sometimes cause confusion or unexpected behavior if the developer isn’t mindful.

For example, exporting a default alongside named exports looks like this:

export default function mainFeature() {
  // ...
}

export function helper() {
  // ...
}

When importing, you can do:

import mainFeature, { helper } from './module.js';

This flexibility is powerful but requires discipline in module design to keep your API surface intuitive and consistent. If you find yourself exporting many named functions alongside a default export, consider whether the module is doing too much or if the default export is truly the main entity consumers should use.

In sum, the difference between default and named exports is not just syntax but a semantic signal about the module’s purpose. Internalizing this distinction leads to cleaner, more maintainable codebases and a better developer experience when consuming modules.

Now, when you start combining default and named exports in the same module, you need to be precise about the import syntax to avoid ambiguity and make your code readable. The next point covers how to manage that combination effectively, ensuring you get the best of both worlds without confusion. Let’s look at how

Combining default and named exports in a single module

you can structure your imports to maintain clarity. When you have both default and named exports, it’s essential to keep track of what you’re importing to ensure that your code remains understandable. One effective practice is to keep the default import separate from named imports, as shown below:

import mainFeature from './module.js';
import { helper } from './module.js';

This separation can enhance readability, especially in larger modules where multiple exports exist. By importing the default export on its own line, you signal to anyone reading the code that that is the primary functionality the module provides, while named imports follow as supplementary utilities.

Another approach is to import everything as a namespace, which can be particularly useful when dealing with many exports. Here’s how you can do that:

import * as module from './module.js';

module.mainFeature();
module.helper();

Using a namespace import clarifies which module the functions belong to, reducing the risk of name collisions and improving maintainability. However, it can also lead to verbose code, so it is essential to balance the benefits of clarity against the potential for clutter.

In practice, consider how often each function will be used. If a default export represents the main functionality of the module while named exports serve as auxiliary functions, then a clear distinction in how you import them will benefit the overall design. For instance, if you find that the named exports are frequently used, it may be worth revisiting the module structure to see if they should be part of a different module altogether.

When dealing with mixed exports, another best practice is to document your exports clearly. This can be done through comments or documentation tools that can generate API docs from your code. Here’s a simple example of how you might document your exports:

/**
 * Main feature of the module.
 * @returns {void}
 */
export default function mainFeature() {
  // ...
}

/**
 * Helper function to assist with calculations.
 * @param {number} value
 * @returns {number}
 */
export function helper(value) {
  // ...
}

By providing clear documentation, you enhance the usability of your module for other developers, making it easier to understand the purpose and usage of each export. In addition, using JSDoc-style comments can integrate well with various IDEs to provide inline documentation, further enhancing the developer experience.

While combining default and named exports can introduce complexity, adhering to these practices can mitigate confusion. It promotes a clear understanding of your module’s structure and purpose, allowing consumers to leverage your code effectively. As you refine your approach to module design, remember that clarity and intent are paramount, especially as your codebase grows.

Ultimately, the goal is to create a module system that is intuitive and easy to navigate. By being deliberate in your export choices and import strategies, you can craft a module ecosystem that serves both current and future developers well, leading to a more cohesive and effective codebase. As you implement these strategies, consider how they align with your overall architecture and whether they facilitate the kind of collaboration and maintenance you envision for your project. The choices you make today will

Best practices for importing mixed exports in your code

When importing mixed exports—both default and named—it’s important to adopt consistent patterns that reduce cognitive load and improve maintainability. A common and clear pattern is to import the default export first, followed by named exports enclosed in curly braces, like this:

import mainFeature, { helper, utility } from './module.js';

This syntax clearly distinguishes the primary export from the supporting utilities. It also keeps your import statements concise and easy to scan, especially when you’re importing many named exports alongside a default.

In cases where you only need a few named exports and the default export is not required, avoid importing the default unnecessarily. This keeps the import footprint minimal and communicates intent better:

import { helper, utility } from './module.js';

Conversely, if the default export is the primary focus, avoid importing all named exports just because they exist. This reduces clutter and improves code readability:

import mainFeature from './module.js';

When you need to import many named exports, or if you want to group all exports under a single namespace to prevent name collisions, use the namespace import pattern:

import * as module from './module.js';

module.mainFeature();
module.helper();
module.utility();

Namespace imports are particularly useful in large codebases or when working with modules that have many exports, as they keep the global scope clean and make it explicit which module each function or variable belongs to.

Be mindful when mixing namespace imports with default imports. Since the default export is available on the default property of the namespace object, you access it like this:

import * as module from './module.js';

module.default();

This can be less intuitive than importing the default export directly, so choose your import style based on how you want to express the module’s API in your code.

Another best practice is to consistently rename your imports when necessary to avoid clashes or improve clarity. Use the as keyword to alias named imports:

import mainFeature, { helper as calculateHelper } from './module.js';

calculateHelper();

This makes your code more readable and prevents confusion when different modules export functions or variables with the same name.

Also, consider grouping related named exports into submodules if your module grows too large. This reduces complexity and improves import clarity. For example, instead of:

import mainFeature, { helper, utility, anotherHelper, extraUtility } from './largeModule.js';

Split it into smaller modules like:

import mainFeature from './largeModule.js';
import { helper, anotherHelper } from './helpers.js';
import { utility, extraUtility } from './utilities.js';

This approach aligns with the Single Responsibility Principle at the module level and makes imports more manageable.

Finally, always keep your imports organized and consistent within a project or team. Group default imports, named imports, and namespace imports separately, and avoid mixing styles unnecessarily. Many linters and style guides enforce these patterns to improve code quality.