JavaScript Modules Guide

ES modules provide a standard way to organize and share JavaScript code. Here's how to use them effectively.

Basic Export and Import#

// math.js - Named exports
export const PI = 3.14159;

export function add(a, b) {
  return a + b;
}

export function multiply(a, b) {
  return a * b;
}

// app.js - Named imports
import { PI, add, multiply } from './math.js';

console.log(PI);           // 3.14159
console.log(add(2, 3));    // 5
console.log(multiply(2, 3)); // 6

Default Exports#

// user.js - Default export
export default class User {
  constructor(name) {
    this.name = name;
  }

  greet() {
    return `Hello, ${this.name}`;
  }
}

// app.js - Import default
import User from './user.js';

const user = new User('John');
user.greet();

// Default with named exports
export default function main() {}
export const VERSION = '1.0.0';

// Import both
import main, { VERSION } from './module.js';

Import Variations#

// Rename on import
import { add as sum, multiply as mul } from './math.js';
sum(2, 3);  // 5

// Import all as namespace
import * as math from './math.js';
math.add(2, 3);
math.PI;

// Import default with namespace
import User, * as utils from './module.js';

// Side-effect import (just execute)
import './polyfills.js';
import './styles.css';  // With bundlers

// Import assertions (JSON)
import data from './data.json' with { type: 'json' };

Export Variations#

// Inline export
export const name = 'John';
export function greet() {}
export class User {}

// Export list
const name = 'John';
function greet() {}
class User {}

export { name, greet, User };

// Rename on export
export { name as userName, greet as sayHello };

// Re-export from another module
export { add, multiply } from './math.js';
export * from './utils.js';
export * as math from './math.js';

// Re-export default
export { default } from './module.js';
export { default as User } from './user.js';

Dynamic Imports#

// Static import (top-level, hoisted)
import { add } from './math.js';

// Dynamic import (returns Promise)
async function loadModule() {
  const math = await import('./math.js');
  math.add(2, 3);
}

// Conditional loading
if (condition) {
  const { feature } = await import('./feature.js');
  feature();
}

// Lazy loading with routes
const routes = {
  '/': () => import('./pages/home.js'),
  '/about': () => import('./pages/about.js'),
  '/contact': () => import('./pages/contact.js')
};

async function loadPage(path) {
  const loader = routes[path];
  if (loader) {
    const module = await loader();
    module.render();
  }
}

// Error handling
try {
  const module = await import('./optional-feature.js');
  module.init();
} catch (err) {
  console.log('Feature not available');
}

Module Patterns#

// Barrel exports (index.js)
// components/index.js
export { Button } from './Button.js';
export { Input } from './Input.js';
export { Modal } from './Modal.js';
export * from './utils.js';

// Import from barrel
import { Button, Input, Modal } from './components/index.js';
// Or: import { Button } from './components';  // With bundler

// Factory pattern
// logger.js
function createLogger(prefix) {
  return {
    log: (msg) => console.log(`[${prefix}] ${msg}`),
    error: (msg) => console.error(`[${prefix}] ${msg}`)
  };
}

export default createLogger;

// Singleton pattern
// config.js
class Config {
  constructor() {
    this.settings = {};
  }

  set(key, value) {
    this.settings[key] = value;
  }

  get(key) {
    return this.settings[key];
  }
}

export default new Config();  // Single instance exported

Circular Dependencies#

// a.js
import { b } from './b.js';
export const a = 'A';
console.log('a:', b);  // Might be undefined!

// b.js
import { a } from './a.js';
export const b = 'B';
console.log('b:', a);  // Might be undefined!

// Solution 1: Use functions (deferred access)
// a.js
import { getB } from './b.js';
export const a = 'A';
export function getA() { return a; }
console.log('a:', getB());

// b.js
import { getA } from './a.js';
export const b = 'B';
export function getB() { return b; }
console.log('b:', getA());

// Solution 2: Restructure to avoid cycles
// shared.js
export const shared = {};

// a.js
import { shared } from './shared.js';
shared.a = 'A';

// b.js
import { shared } from './shared.js';
shared.b = 'B';

Module Scope#

// Each module has its own scope
// module-a.js
const secret = 'hidden';
export const visible = 'public';

// module-b.js
import { visible } from './module-a.js';
// secret is not accessible

// Top-level await (in modules)
const data = await fetch('/api/config').then(r => r.json());
export default data;

// Module-level this
console.log(this);  // undefined (not window)

// import.meta
console.log(import.meta.url);  // Module's URL
// In Node.js
import.meta.dirname  // Directory path
import.meta.filename // File path

Node.js Specifics#

// package.json
{
  "type": "module"  // Enable ES modules
}

// Or use .mjs extension
// math.mjs

// CommonJS interop
import fs from 'fs';  // Works with Node built-ins
import pkg from './package.json' with { type: 'json' };

// Named imports from CommonJS (sometimes works)
import { readFile } from 'fs';

// Default import always works
import lodash from 'lodash';

// Import CommonJS as namespace
import * as _ from 'lodash';

// __dirname and __filename alternatives
import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Browser Usage#

<!-- ES module in browser -->
<script type="module" src="app.js"></script>

<!-- Inline module -->
<script type="module">
  import { greet } from './greet.js';
  greet('World');
</script>

<!-- Fallback for older browsers -->
<script nomodule src="legacy-bundle.js"></script>

<!-- Import maps -->
<script type="importmap">
{
  "imports": {
    "lodash": "https://cdn.skypack.dev/lodash",
    "@utils/": "./src/utils/"
  }
}
</script>

<script type="module">
  import _ from 'lodash';
  import { helper } from '@utils/helper.js';
</script>

Module Design#

// Keep exports focused
// ❌ Too many exports
export { a, b, c, d, e, f, g, h, i, j };

// ✓ Grouped with namespace or barrel
import * as validators from './validators/index.js';

// Prefer named exports for utilities
export function formatDate(date) {}
export function formatCurrency(amount) {}

// Use default for main class/function
export default class UserService {}

// Export types alongside values (TypeScript)
export interface User {
  id: number;
  name: string;
}

export function createUser(name: string): User {
  return { id: Date.now(), name };
}

Tree Shaking#

// Tree shaking removes unused exports
// utils.js
export function used() {
  return 'This is used';
}

export function unused() {
  return 'This will be removed';
}

// app.js
import { used } from './utils.js';
// unused() is removed from bundle

// Side effects prevent tree shaking
// ❌ Has side effects
let cache = {};
export function getData() {
  return cache;
}

// ✓ Mark as side-effect free
// package.json
{
  "sideEffects": false
}

// Or list files with side effects
{
  "sideEffects": ["./src/polyfills.js", "*.css"]
}

Testing with Modules#

// Easy to test with ES modules
// calculator.js
export function add(a, b) {
  return a + b;
}

// calculator.test.js
import { add } from './calculator.js';

test('add', () => {
  expect(add(2, 3)).toBe(5);
});

// Mock modules
jest.mock('./api.js', () => ({
  fetchUser: jest.fn(() => Promise.resolve({ name: 'Mock' }))
}));

import { fetchUser } from './api.js';

Best Practices#

Export Design:
✓ One module = one responsibility
✓ Named exports for utilities
✓ Default export for main item
✓ Use barrel files for public API

Import Organization:
✓ External packages first
✓ Internal absolute paths
✓ Relative paths last
✓ Group by type

File Structure:
✓ index.js for public API
✓ Consistent naming
✓ Colocate related code
✓ Avoid deep nesting

Avoid:
✗ Circular dependencies
✗ Wildcard re-exports (*)
✗ Importing from deep paths
✗ Side effects in modules

ES modules are the standard for JavaScript code organization. Use named exports for utilities and default exports for main functionality. Leverage dynamic imports for code splitting, barrel files for clean public APIs, and import maps for browser deployment. Keep modules focused, avoid circular dependencies, and design for tree shaking to create maintainable, efficient code.