Writing large programs in JavaScript without modules would be pretty difficult. Imagine you only have the global scope to work with. This was the situation in JavaScript before modules. Scripts attached to the DOM were prone to overwriting each other and variable name conflicts.
With JavaScript modules, you have the ability to create private scopes for your code, and also explicitly state which parts of your code should be globally accessible.
JavaScript modules are not just a way of splitting code across files, but mainly a way to design boundaries between parts of your system.
Behind every technology, there should be a guide for its use. While JavaScript modules make it easier to write “big” programs, if there are no principles or systems for using them, things could easily become difficult to maintain.
The two module systems in JavaScript are CommonJS (CJS) and ECMAScript Modules (ESM).
The CommonJS module system was the first JavaScript module system. It was created to be compatible with server-side JavaScript, and as such, its syntax (require(), module.exports, etc.) was not natively supported by browsers.
The import mechanism for CommonJS relies on the require() function, and being a function, it is not restricted to being called at the top of a module; it can also be called in an if statement or even a loop.
// CommonJS — require() is a function call, can appear anywhere
const module = require('./module')
// this is valid CommonJS — the dependency is conditional and unknowable until runtime
if (process.env.NODE_ENV === 'production') {
const logger = require('./productionLogger')
}
// the path itself can be dynamic — no static tool can resolve this
const plugin = require(`./plugins/${pluginName}`)The same cannot be said for ESM: the import statement has to be at the top. Anything else is regarded as an invalid syntax.
// ESM — import is a declaration, not a function call
import { formatDate } from './formatters'
// invalid ESM — imports must be at the top level, not conditional
if (process.env.NODE_ENV === 'production') {
import { logger } from './productionLogger' // SyntaxError
}
// the path must be a static string — no dynamic resolution
import { plugin } from `./plugins/${pluginName}` // SyntaxError: : template literals are dynamic pathsYou can see that CommonJS gives you more flexibility than ESM. But if ESM was created after CommonJS, why wasn’t this flexibility implemented in ESM too, and how does it affect your code?
The answer comes down to static analysis and tree-shaking. With CommonJS, static tools cannot determine which modules are needed for your program to run in order to remove the ones that aren’t needed. And when a bundler is not sure whether a module is needed or not, it includes it by default. The way CommonJS is defined, modules that depend on each other can only be known at runtime.
ESM was designed to fix this. By making sure the position of import statements is restricted to the top of the file and that paths are static string literals, static tools can better understand the structure of the dependencies in the code and eliminate the modules that aren’t needed, which in turn, makes bundle sizes smaller.
Whether you are aware of it or not, every time you create, import, or export modules, you are shaping the structure of your application. This is because modules are the basic building blocks of a project architecture, and the interaction between these modules is what makes an application functional and useful.
The organization of modules defines boundaries, shapes the flow of your dependencies, and even mirrors your team’s organizational structure. The way you manage the modules in your project can either make or break your project.
There are so many ways to structure a project, and there is no one-size-fits-all method to organize every project.
Clean architecture is a controversial methodology and not every team should adopt it. It might even be over-engineering, especially smaller projects. However, if you don’t have a strict option for structuring a project, then the clean architecture approach could be a good place to start.
According to Robert Martin’s dependency rule:
“Nothing in an inner circle can know anything at all about something in an outer circle.”
Robert C. Martin
Based on this rule, an application should be structured in different layers, where the business logic is the application’s core and the technologies for building the application are positioned at the outermost layer. The interface adapters and business rules come in between.
From the diagram, the first block represents the outer circle and the last block represents the inner circle. The arrows show which layer depends on the other, and the direction of dependencies flow towards the inner circle. This means that the framework and drivers can depend on the interface adapters, and the interface adapters can depend on the use cases layer, and the use cases layer can depend on the entities. Dependencies must point inward and not outward.
So, based on this rule, the business logic layer should not know anything at all about the technologies used in building the application — which is a good thing because technologies are more volatile than business logic, and you don’t want your business logic to be affected every time you have to update your tech stack. You should build your project around your business logic and not around your tech stack.
Without a proper rule, you are probably freely importing modules from anywhere in your project, and as your project grows, it becomes increasingly difficult to make changes. You’ll eventually have to refactor your code in order to properly maintain your project in the future.
One tool that can help you maintain good project architecture is the module graph. A module graph is a type of dependency flow that shows how different modules in a project rely on each other. Each time you make imports, you are shaping the dependency graph of your project.
A healthy dependency graph could look like this:
From the graph, you can see dependencies flowing in one direction (following the dependency rule), where high-level modules depend on low-level ones, and never the other way around.
Conversely, this is what an unhealthy one might look like:
From the above graph above, you can see that utils.js is no longer a dependency of response.js and application.js as we would find in a healthy graph, but is also dependent on request.js and view.js. This level of dependence on utils.js increases the blast radius if anything goes wrong with it. And it also makes it harder to run tests on the module.
Yet another issue we can point out with utils.js is how it depends on request.js this goes against the ideal flow for dependencies. High-level modules should depend on low-level ones, and never the reverse.
So, how can we solve these issues? The first step is to identify what’s causing the problem. All of the issues with utils.js are related to the fact that it is doing too much. That’s where the Single Responsibility Principle comes into play. Using this principle, utils.js can be inspected to identify everything it does, then each cohesive functionality identified from utils.js can be extracted into its own focused module. This way, we won’t have so many modules that are dependent on utils.js, leading to a more stable application.
Moving on from utils.js, we can see from the graph that there are now two circular dependencies:
express.js → application.js → view.js → express.jsresponse.js → utils.js→ view.js→ response.jsCircular dependencies occur when two or more modules directly or indirectly depend on each other. This is bad because it makes it hard to reuse a module, and any change made to one module in the circular dependency is likely to affect the rest of the modules.
For example, in the first circular dependency (express.js → application.js → view.js → express.js), if view.js breaks, application.js will also break because it depends on view.js — and express.js will also break because it depends on application.js.
You can begin checking and managing your module graphs with tools such as Madge and Dependency Cruiser. Madge allows you to visualize module dependencies, while Dependency Cruiser goes further by allowing you to set rules on which layers of your application are allowed to import from which other layers.
Understanding the module graph can help you optimize build times and fix architectural issues such as circular dependency and high coupling.
One common way the JavaScript module system is being used is through barrel files. A barrel file is a file (usually named something like index.js/index.ts) that re-exports components from other files. Barrel files provide a cleaner way to handle a project’s imports and exports.
Suppose we have the following files:
// auth/login.ts
export function login(email: string, password: string) {
return `Logging in ${email}`;
}
// auth/register.ts
export function register(email: string, password: string) {
return `Registering ${email}`;
}Without barrel files, this is how the imports look:
// somewhere else in the app
import { login } from '@/features/auth/login';
import { register } from '@/features/auth/register';Notice how the more modules we need in a file, the more import lines we’re going to have in that file.
Using barrel files, we can make our imports look like this:
// somewhere else in the app
import { login, register } from '@/features/auth';And the barrel file handling the exports will look like this:
// auth/index.ts
export * from './login';
export * from './register';Barrel files provide a cleaner way to handle imports and exports. They improve code readability and make it easier to refactor code by reducing the lines of imports you have to manage. However, the benefits they provide come at the expense of performance (by prolonging build times) and less effective tree shaking, which, of course, results in larger JavaScript bundles. Atlassian, for instance, reported to have achieved 75% faster builds, and a slight reduction in their JavaScript bundle size after removing barrel files from their Jira application’s front-end.
For small projects, barrel files are great. But for larger projects, I’d say they improve code readability at the expense of performance. You can also read about the effects barrel files had on the MSW library project.
Coupling describes how the components of your system rely on each other. In practice, you cannot get rid of coupling, as different parts of your project need to interact for them to function well. However, there are two types of coupling you should avoid: (1) tight coupling and (2) implicit coupling.
Tight coupling occurs when there is a high degree of interdependence between two or more modules in a project such that the dependent module relies on some of the implementation details of the dependency module. This makes it hard (if not impossible) to update the dependency module without touching the dependent module, and, depending on how tightly coupled your project is, updating one module may require updating several other modules — a phenomenon known as change amplification.
Implicit coupling occurs when one module in your project secretly depends on another. Patterns like global singletons, shared mutable state, and side effects can cause implicit coupling. Implicit coupling can reduce inaccurate tree shaking, unexpected behavior in your code, and other issues that are difficult to trace.
While coupling cannot be removed from a system, it is important that:
When building large scale applications, different modules of the application are usually assigned to different teams. Depending on who owns the modules, boundaries are created, and these boundaries can be characterized as one of the following:
There must be some form of communication regardless of the type of collaboration. With Conway’s Law, we can better infer how different levels of communication coupled with the different types of ownership can affect software architecture.
Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure.
Based on this, here are some assumptions we can make:
| Good Communication | Poor Communication | |
|---|---|---|
| Weak Code Ownership | Architecture may still emerge, but boundaries remain unclear | Fragmented, inconsistent architecture |
| Strong Code Ownership | Clear, cohesive architecture aligned with ownership boundaries | Disconnected modules; integration mismatches |
| Collective Code Ownership | Highly collaborative, integrated architecture | Blurred boundaries; architectural drift |
Here’s something to keep in mind whenever you define module boundaries: Modules that frequently change together should share the same boundary, since shared evolution is a strong signal that they represent a single cohesive unit.
Structuring a large project goes beyond organizing files and folders. It involves creating boundaries through modules and coupling them together to form a functional system. By being deliberate about your project architecture, you save yourself from the hassle that comes with refactoring, and you make your project easier to scale and maintain.
If you have existing projects you’d like to manage and you don’t know where to start, you can begin by installing Madge or Dependency Cruiser. Point Madge at your project, and see what the graph actually looks like. Check for circular dependencies and modules with arrows coming in from everywhere. Ask yourself if what you see is what you planned your project to look like.
Then, you can proceed by enforcing boundaries, breaking circular chains, moving modules and extracting utilities. You don’t need to refactor everything at once — you can make changes as you go. Also, if you don’t have an organized system for using modules, you need to start implementing one.
Are you letting your module structure happen to you, or are you designing it?
A Well-Designed JavaScript Module System is Your First Architecture Decision originally handwritten and published with love on CSS-Tricks. You should really get the newsletter as well.
Managing state in CSS is not exactly the most obvious thing in the world, and to be honest, it is not always the best choice either. If an interaction carries business logic, needs persistence, depends on data, or has to coordinate multiple moving parts, JavaScript is usually the right tool for the job.
That said, not every kind of state deserves a trip through JavaScript.
Sometimes we are dealing with purely visual UI state: whether a panel is open, an icon changed its appearance, a card is flipped, or whether a decorative part of the interface should move from one visual mode to another.
In cases like these, keeping the logic in CSS can be not just possible, but preferable. It keeps the behavior close to the presentation layer, reduces JavaScript overhead, and often leads to surprisingly elegant solutions.
One of the best-known examples of CSS state management is the checkbox hack.
If you have spent enough time around CSS, you have probably seen it used for all kinds of clever UI tricks. It can be used to restyle the checkbox itself, toggle menus, control inner visuals of components, reveal hidden sections, and even switch an entire theme. It is one of those techniques that feels slightly mischievous the first time you see it, and then immediately becomes useful.
If you have never used it before, the checkbox hack concept is very simple:
<input type="checkbox" id="state-toggle" hidden>label to it, so the user can toggle it from anywhere we want.<label for="state-toggle" class="state-button">
Toggle state
</label>:checked state and sibling combinators to style other parts of the page based on whether that checkbox is checked.#state-toggle:checked ~ .element {
/* styles when the checkbox is checked */
}
.element {
/* default styles */
}In other words, the checkbox becomes a little piece of built-in UI state that CSS can react to. Here is a simple example of how it can be used to switch between light and dark themes:
:has()Note that I’ve placed the checkbox at the top of the document, before the rest of the content. This was important in the days before the :has() pseudo-class, because CSS only allowed us to select elements that come after the checkbox in the DOM. Placing the checkbox at the top was a way to ensure that we could target any element in the page with our selectors, regardless of the label position in the DOM.
But now that :has() is widely supported, we can place the checkbox anywhere in the document, and still target elements that come before it. This gives us much more flexibility in how we structure our HTML. For example, we can place the checkbox right next to the label, and still control the entire page with it.
Here is a classic example of the checkbox hack theme selector, with the checkbox placed next to the label, and using :has() to control the page styles:
<div class="content">
<!-- content -->
</div>
<label class="theme-button">
<input type="checkbox" id="theme-toggle" hidden>
Toggle theme
</label>body {
/* other styles */
/* default to dark mode */
color-scheme: dark;
/* when the checkbox is checked, switch to light mode */
&:has(#theme-toggle:checked) {
color-scheme: light;
}
}
/* use the color `light-dark()` on the content */
.content {
background-color: light-dark(#111, #eee);
color: light-dark(#fff, #000);
}Note: I’m using the ID selector (#) in the CSS as it is already part of the checkbox hack convention, and it is a simple way to target the checkbox. If you worry about CSS selectors performance, don’t.
Note I’ve been using the HTML hidden global attribute to hide the checkbox from view. This is a common practice in the checkbox hack, as it keeps the input in the DOM and allows it to maintain its state, while removing it from the visual flow of the page.
Sadly, the hidden attribute also hides the element from assistive technologies, and the label that controls it does not have any interactive behavior on its own, which means that screen readers and other assistive devices will not be able to interact with the checkbox.
This is a significant accessibility concern, and to fix this, we need a different approach: instead of wrapping the checkbox in a label and hiding it with hidden, we can turn the checkbox into the button itself.
<input type="checkbox" class="theme-button" aria-label="Toggle theme">No hidden, no label, just a fully accessible checkbox. And to style it like a button, we can use the appearance property to remove the default checkbox styling and apply our own styles.
.theme-button {
appearance: none;
cursor: pointer;
font: inherit;
color: inherit;
/* other styles */
/* Add text using a simple pseudo-element */
&::after {
content: "Toggle theme";
}
}This way, we get a fully accessible toggle button that still controls the state of the page through CSS, without relying on hidden inputs or labels. And we’re going to use this approach in all the following examples as well.
So, the checkbox hack is a great way to manage simple binary state in CSS, but it also has a very clear limitation. A checkbox gives us two states: checked and not checked. On and off. That is great when the UI only needs a binary choice, but it is not always enough.
What if we want a component to be in one of three, four, or seven modes? What if a visual system needs a proper set of mutually exclusive states instead of a simple toggle?
That is where the Radio State Machine comes in.
The core idea is very similar to the checkbox hack, but instead of a single checkbox, we use a bunch of radio buttons. Each radio button represents a different state, and because radios let us choose one option out of many, they give us a surprisingly flexible way to build multi-state visual systems directly in CSS.
Let’s break down how this works:
<div class="state-button">
<input type="radio" name="state" data-state="one" aria-label="state one" checked>
<input type="radio" name="state" data-state="two" aria-label="state two">
<input type="radio" name="state" data-state="three" aria-label="state three">
</div>We created a group of radio buttons. Note that they all share the same name attribute (state in this case). This ensures that only one radio can be selected at a time, giving us mutually exclusive states.
We gave each radio button a unique data-state that we can target in CSS to apply different styles based on which state is selected, and the checked attribute to set the default state (in this case, one is the default).
The style for the radio buttons themselves is similar to the checkbox button we created earlier. We use appearance: none to remove the default styling, and then apply our own styles to make them look like buttons.
input[name="state"] {
appearance: none;
padding: 1em;
border: 1px solid;
font: inherit;
color: inherit;
cursor: pointer;
user-select: none;
/* Add text using a pseudo-element */
&::after {
content: "Toggle State";
}
&:hover {
background-color: #fff3;
}
}The main difference is that we have multiple radio buttons, each representing a different state, and we only need to show the one for the next state in the sequence, while hiding the others. We can’t use display: none on the radio buttons themselves, because that would make them inaccessible, but we can achieve this by adding a few properties as a default, and overriding them for the radio button we want to show.
position: fixed; to take the radio buttons out of the normal flow of the page.pointer-events: none; to make sure the radio buttons themselves are not clickable.opacity: 0; to make the radio buttons invisible.That will hide all the radio buttons by default, while keeping them in the DOM and accessible.
Then we can show the next radio button in the sequence by targeting it with the adjacent sibling combinator (+) when the current radio button is checked. This way, only one radio button is visible at a time, and users can click on it to move to the next state.
input[name="state"] {
/* other styles */
position: fixed;
pointer-events: none;
opacity: 0;
&:checked + & {
position: relative;
pointer-events: all;
opacity: 1;
}
}And to make the flow circular, we can also add a rule to show the first radio button when the last one is checked. This is, of course, optional, and we’ll talk about linear and bi-directional flows later.
&:first-child:has(~ :last-child:checked) {}One last touch is to add an outline to the radio buttons container. As we are always hiding the checked radio buttons, we are also hiding its outline. By adding an outline to the container, we can ensure that users can still see where they are when they navigate through the states using the keyboard.
.state-button:has(:focus-visible) {
outline: 2px solid red;
}Now we can add styles for each state using the :checked selector to target the selected radio button. Each state will have its own unique styles, and we can use the data-state attribute to differentiate between them.
body {
/* other styles */
&:has([data-state="one"]:checked) .element {
/* styles when the first radio button is checked */
}
&:has([data-state="two"]:checked) .element {
/* styles when the second radio button is checked */
}
&:has([data-state="three"]:checked) .element {
/* styles when the third radio button is checked */
}
}
.element {
/* default styles */
}And, of course, this pattern can be used for far more than a simple three-state toggle. The same idea can power steppers, view switchers, card variations, visual filters, layout modes, small interactive demos, and even more elaborate CSS-only toys. Some of these use cases are mostly practical, some are more playful, and we are going to explore a few of them later in this article.
Now that we are back to keeping all the state inputs in one place, and we are already leaning on :has(), we get another very practical advantage: custom properties.
In previous examples, we often set the final properties directly per state, which meant targeting the element itself each time. That works, but it can get noisy fast, especially as the selectors become more specific and the component grows.
A cleaner pattern is to assign state values to variables at a higher level, take advantage of how custom properties naturally cascade down, and then consume those variables wherever needed inside the component.
For example, we can define --left and --top per state:
body {
/* ... */
&:has([data-state="one"]:checked) {
--left: 48%;
--top: 48%;
}
&:has([data-state="two"]:checked) {
--left: 73%;
--top: 81%;
}
/* other states... */
}Then we simply consume those values on the element itself:
.map::after {
content: '';
position: absolute;
left: var(--left, 50%);
top: var(--top, 50%);
/* ... */
}This keeps state styling centralized, reduces selector repetition, and makes each component class easier to read because it only consumes variables instead of re-implementing state logic.
Once we move state into variables, we can also treat state as a number and start doing calculations.
Instead of assigning full visual values for every state, we can define a single numeric variable:
body {
/* ... */
&:has([data-state="one"]:checked) { --state: 1; }
&:has([data-state="two"]:checked) { --state: 2; }
&:has([data-state="three"]:checked) { --state: 3; }
&:has([data-state="four"]:checked) { --state: 4; }
&:has([data-state="five"]:checked) { --state: 5; }
}Now we can take that value and use it in calculations on any element we want. For example, we can drive the background color directly from the active state:
.card {
background-color: hsl(calc(var(--state) * 60) 50% 50%);
}And if we define an index variable like --i per item (at least until sibling-index() is more widely available), we can calculate each item’s style, like position and opacity, relative to the active state and its place in the sequence.
.card {
position: absolute;
transform:
translateX(calc((var(--i) - var(--state)) * 110%))
scale(calc(1 - (abs(var(--i) - var(--state)) * 0.3)));
opacity: calc(1 - (abs(var(--i) - var(--state)) * 0.4));
}This is where the pattern becomes really fun: one --state variable drives an entire visual system. You are no longer writing separate style blocks for every card in every state. You define a rule once, give each item its own index (--i), and let CSS do the rest.
You may have noticed that unlike the earlier demos, the last example was not circular. Once you reach the last state, you get stuck there. This is because I removed the rule that shows the first radio button when the last one is checked, and instead added a disabled radio button as a placeholder that appears when the last state is active.
<input type="radio" name="state" disabled>This pattern is useful for progressive flows like onboarding steps, checkout progress, or multi-step setup forms where the final step is a real endpoint. That said, the states are still accessible through keyboard navigation, and that is a good thing, unless you don’t want it to be.
In that case, you can replace the position, pointer-events, and opacity properties with display: none as a default, and display: block (or inline-block, etc.) for the one that should be visible and interactive. This way, the hidden states will not be focusable or reachable by keyboard users, and the flow will be truly linear.
Of course, interaction should not only move forward. Sometimes users need to go back too, so we can add a “Previous” button by also showing the radio button that points to the previous state in the sequence.
To update the CSS so each state reveals not one, but two radio buttons, we need to expand the selectors to target both the next and previous buttons for each state. We select the next button like before, using the adjacent sibling combinator (+), and the previous button using :has() to look for the checked state on the next button (:has(+ :checked)).
input[name="state"] {
position: fixed;
pointer-events: none;
opacity: 0;
/* other styles */
&:has(+ :checked),
&:checked + & {
position: relative;
pointer-events: all;
opacity: 1;
}
/* Set text to "Next" as a default */
&::after {
content: "Next";
}
/* Change text to "Previous" when the next state is checked */
&:has(+ :checked)::after {
content: "Previous";
}
}This way, users can navigate in either direction through the states.
This is a simple extension of the previous logic, but it gives us much more control over the flow of the state machine, and allows us to create more complex interactions while still keeping the state management in CSS.
Before wrapping up, one important reminder: this pattern should stay visual in responsibility, but accessible in behavior. Because the markup is built on real form controls, we already get a strong baseline, but we need to be deliberate about accessibility details:
In short: the radio state machine works best when it enhances interaction, not when it replaces semantics or application logic.
The radio state machine is one of those CSS ideas that feels small at first, and then suddenly opens a lot of creative doors.
With a few well-placed inputs, and a couple of smart selectors, we can build interactions that feel alive, expressive, and surprisingly robust, all while keeping visual state close to the layer that actually renders it.
But it is still just that: an idea.
Use it when the state is mostly visual, local, and interaction-driven. Skip it when the flow depends on business rules, external data, persistence, or complex orchestration.
Believe me, if there were a prize for forcing complex state management into CSS just because we technically can, I would have won it long ago. The real win is not proving CSS can do everything, but learning exactly where it shines.
So here is the challenge: pick one tiny UI in your project, rebuild it as a mini state machine, and see what happens. If it becomes cleaner, keep it. If it gets awkward, roll it back with zero guilt. And don’t forget to share your experiments.
The Radio State Machine originally handwritten and published with love on CSS-Tricks. You should really get the newsletter as well.
With a high of F and a low of 34F. Currently, it's 62F and Clear outside. Current wind speeds: 15 from the Southwest Pollen: 0 S...
