DEV Community: Fogel

How Default Settings and Bad Habits Are Draining Your Claude Code Budget

Fogel — Wed, 23 Sep 2026 09:24:47 +0000

Introduction

Many developers use Claude Code and look for ways to reduce token consumption by using skills and external tools.

But what if I told you that Claude Code includes several features enabled by default that silently impact your costs - through additional background API calls, bloating your context window, and breaking the prompt cache?

Beyond settings, our workflow habits have a significant impact. The way we run commands, fix mistakes, ask side questions, and manage long sessions can dramatically affect context size and the number of API calls made.

This article focuses on costs during ongoing work with Claude Code. For this purpose, I analyzed configuration files, environment variables, and actual API network traffic to understand what is really being sent to the model under the hood.

The goal isn't to argue that you should turn off every single feature, but rather to raise awareness of their hidden costs, allowing you to choose whether the benefit of each feature justifies its price.

This article is a follow-up to my previous article, where I explained how you can save up to 49% on a session's initial context.

Baseline Assumptions

Claude Code version 2.1.278
Claude Opus 5 model, unless specified otherwise.
A Claude subscription which, according to Claude Code documentation, utilizes a one-hour TTL cache.

Features that consume tokens

Session recap

When we are in the middle of a session and no interaction occurs for at least 3 minutes, Claude Code generates a short summary of the conversation.

Is it added to the context?

The short summary is not added to the context.

Does this action consume tokens?

Yes. Generating the summary triggers an additional background API request that reuses the session's prompt cache. This action can run multiple times throughout a single session.

My recommendation

I recommend disabling it. If you ever need a summary, you can easily trigger it manually using the /recap command.

How to disable

You can disable this via the /config menu or by setting awaySummaryEnabled: false in your settings.json file.

Prompt suggestions

After receiving a response from Claude, it usually provides a prompt suggestion as a follow-up, which you can accept by pressing Tab and then Enter.

Is it added to the context?

Not added, as long as you don't use the suggested prompt.

Does this action consume tokens?

The prompt suggestion typically occurs after every single response Claude gives us. It runs as an additional background API request that reuses the session's prompt cache. This action can run many times during a session.

My recommendation

I rarely use Claude's suggestions, so the cost of this feature isn't worth it for me.

How to disable

You can disable this via the /config menu, or by setting promptSuggestionEnabled: false in settings.json, or by using the environment variable CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION: false.

`opusplan` model setting

This represents an automatic hybrid approach.
When the opusplan model is set, the transition between Opus and Sonnet models happens dynamically when entering or exiting plan mode.

Switching models mid-conversation invalidates the prompt cache, resulting in paying 20x to 80x more to rewrite tokens to the cache.

Auto memory

Auto memory allows Claude to accumulate knowledge and insights between sessions automatically without requiring us to write anything manually.

Is it added to the context?

Yes. You can read a detailed breakdown of its impact on the context in my previous article - How to Reduce Claude Code's Initial Context and Avoid Prompt Cache Breaks.

Does this action consume tokens?

Yes. During the conversation with Claude, the auto memory file (MEMORY.md) is updated, which consumes tokens.

My recommendation

I find it unnecessary. It can cause conflicts between the memory and other information in the context, and it takes up valuable context space.

How to disable

You can disable this via /memory, or by adding "autoMemoryEnabled": false to your settings.json, or by setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Auto mode

Claude Code features several permission modes:

default - Manual mode
acceptEdits
plan
auto
dontAsk
bypassPermissions

Note that default is not the actual default behavior. It is simply the name of the manual mode. The actual default permission mode is auto mode.

Auto mode allows a classifier model to decide on its own whether to approve an action or not. This classifier model uses Claude Sonnet 5 (as seen under "Cost and latency" in the link).

plan mode uses auto mode when available.

Does this action consume tokens?

Yes. Every permission decision automatically sends an API call to the classifier model, consuming additional tokens.

My recommendation

Use acceptEdits mode combined with pre-approving specific commands. For example:

JSON

{
"permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run build)", "Bash(npm test:*)", "Bash(git diff:*)", "Bash(git status)"]
  }
}

How to disable

Disable Auto Mode entirely

You can completely prevent the use of auto mode by setting disableAutoMode: "disable" in settings.json. This will force the use of default (manual) mode as the default.

Prevent Auto Mode during Plan Mode

Additionally, you can prevent auto mode usage during plan mode by toggling "Use auto mode during plan" in /config or set "useAutoModeDuringPlan": false in settings.json.

Shell mode with `!` prefix

You can run shell commands directly in Claude Code by prefixing the command with !.

! npm test

In practice, the shell command executes immediately on your machine, and behind the scenes, Claude Code sends both the command and its subsequent output as a prompt. Claude then responds to this prompt.

We could have simply prompted npm test and let Claude Code run it via the shell tool, but that would result in two API calls instead of one and inflate the context even further.

Is it added to the context?

Yes, both the shell command and its output are added to the context.

Does this action consume tokens?

Yes, the shell command and its output are sent as a prompt, consuming tokens as usual. Claude will independently decide how to respond to this output unless we guided it beforehand.

My recommendation

I prefer to review the shell output myself to decide what to do with it before Claude receives it.

Therefore, I configure Claude so the shell command and its output are not sent as a prompt, but only added to the context.

Once it is in the context, I can write a specific prompt telling Claude exactly what to do with that output. Additionally, this gives us the option to change our minds - if we regret running the command, we can use /rewind to remove the shell command and its output from the context before any API call is made.

How to disable

You can configure it so the output is added to the context without triggering a new API call by setting respondToBashCommands: false in settings.json.

Language Server Protocol (LSP) plugins

The LSP is a tool designed for two main purposes:

It immediately identifies syntax/type errors and warnings in your code right after a file edit.
It serves as a highly effective code navigation tool.

There is a Claude Code plugin that connects to the LSP, allowing Claude to receive this data and fix code issues without needing an extra build step to identify them. Furthermore, it allows for much more precise code navigation compared to standard grep-based searches.

Is it added to the context?

Yes, it is added as a tool named "LSP" along with its schema.
When used, the tool call (tool_use) and the LSP's response (tool_result) are added to the context like any other tool.

Does this action consume tokens?

Using LSP actually saves tokens for the following reasons:

After every file edit, the LSP automatically reports errors and warnings, allowing Claude to fix issues without a separate build step.
Code navigation is much more precise and efficient than running a grep command and analyzing the output, which would otherwise fill the context with a large number of irrelevant results.

My recommendation

I believe it is crucial to use this plugin because it saves extra token-consuming API calls and performs actions faster than standard commands Claude would otherwise use, such as grep.

Check out this Reddit post comparing code navigation using Claude Code with and without LSP. The performance difference is clear.

Installing the plugin

The LSP binary and the Claude Code plugin depend on the programming language used in your project. You can find the list of LSP binaries and Claude Code plugins here.
You must install the LSP binary on your machine before installing the Claude plugin.

Context command (`/context`)

A command that outputs the number of tokens in the context, divided by categories (system prompt, system tools, messages, etc.).

Is it added to the context?

The text printed to the screen adds ~2,100 tokens to the context.
Every time you run the command, another 2,100 tokens are added (in addition to the previous ones).

Does this action consume tokens?

The /context command is not billed for tokens because it makes API calls for token counting, not for model inference.
However, because it injects 2,100 tokens into your context, you will pay for those tokens on every single subsequent prompt you send!

My recommendation

Add the token count of the context window to your terminal's statusline so you are always aware of your context window during a session.

Additionally, use this command only at the beginning of a conversation to understand how much space different components (skills, MCPs, etc.) consume, in order to perform context engineering.

Workflow Best Practices (Beyond Settings)

Delegate verbose operations to subagents

Subagents are specialized AI assistants that handle specific types of tasks.

If the main agent were to perform tasks like reading massive log files, it would fill your main conversation's context with irrelevant information. Instead, the main agent can delegate verbose tasks to a subagent, which does the heavy work and returns only the relevant conclusions to the main agent.

A subagent has its own context without the parent's conversation history and does not use the parent's cache.

You can create a custom subagent and configure its initial context, including parameters such as: model to use, effort level, skills to preload, persistent memory scope, and whether to load the CLAUDE.md file.

When using built-in subagents (Explore, Plan, General-purpose) in Claude Code, you can specify which model to use on a per-invocation basis.

Example: Spawn an Explore subagent on Haiku to find X

Use subagents wisely, or you will end up with unnecessary token consumption.

Side questions with `/btw` command

The /btw command is designed for asking a side question about your current session (including the full conversation history) without adding the question and the answer to your main conversation's context, and without using tools.

Because it uses the existing context, it successfully reads from the cache. However, note that the cache write will be for 5 minutes, unlike the 1 hour used in the main conversation.

Rewinding the conversation

If Claude provides an incorrect answer due to a poor prompt or a misunderstanding, don't argue with it in subsequent messages. Explaining "No, that's not what I meant, please undo that and try X" compounds unnecessary context that you will pay for on every subsequent turn.

Instead, run /rewind to roll back the conversation to the turn before the mistake occurred. Fix your initial prompt and regenerate. Your context window stays lean, clean, and focused.

Course-correct early (The ESC Key)

When you see Claude starting to generate an answer and realize it's heading in the wrong direction, you can stop it immediately by pressing the ESC key.

Is it added to the context?

Yes, your prompt and Claude’s partial response are added to the context.

Since this is irrelevant data, you can rewind the context to a previous state using the /rewind command.

Does this action consume tokens?

The act of stopping the generation does not consume tokens. You only pay for what Claude generated up to that point.

Stopping it early actually saves you from paying for the remaining output tokens Claude would have wasted on completing a wrong answer.
Output tokens are significantly more expensive than input tokens (often 5x the price).

Beware of Cache Misses on Idle Sessions

To maximize the benefits of prompt caching on Claude subscriptions, avoid leaving an active session idle for more than an hour without completing the task.

If the 1-hour cache expires, your next prompt will force a full cache rewrite of your entire context. Depending on the model, a cache write is 20x to 80x more expensive than a cache read under 1-hour cache TTL.

My recommendation

Always try to complete your task with Claude without leaving the session idle for over an hour.

Treat your sessions like focused sprints. Aim to finish your current interaction with Claude before taking a long break. Stepping away for more than an hour expires the cache, forcing a full cache rewrite for the entire context.

Resetting to a Clean Session

When we want to start a fresh session, we use the /clear command.

Is it added to the context?

While this initiates a new session, it ironically adds the /clear command itself into the new context, along with text explaining that this is a user command. This adds ~130 tokens.

Does this action consume tokens?

No. The command itself is executed locally and does not trigger an API call or consume tokens.

Workaround

If you want a truly empty context, you have two options:

Restart the Claude Code CLI entirely.
Run the /rewind command and revert to the message that says "/clear". This gives you a completely empty context. Bug Note: There is currently a bug in Claude Code where rewinding to the very beginning of the conversation causes the Skills list to fail to load into the context. This means that if you later want to use a skill, Claude will have to read the skill files manually, which wasting tokens.

Conclusion

Efficient and cost-effective development with Claude Code isn't just about smart prompting. It requires a deep understanding of what happens behind the scenes to make informed use of tokens and properly manage context.
As we've seen, reducing costs comes down to two key areas:

Precise system settings: Disabling default background features (recap summaries, prompt suggestions, classifier auto-modes) and enabling efficient tools like LSP.
Disciplined workflow habits: Interrupting generations early with ESC, rolling back mistakes with /rewind, managing side questions with /btw, and delegating verbose text-analysis tasks to subagents.

Ultimately, the goal isn't to turn off every feature or limit your developer experience, but to manage your environment wisely - ensuring that every token you pay for brings real value to your codebase.

Here is a summary of the settings discussed in this article:

{
  "promptSuggestionEnabled": false,
  "awaySummaryEnabled": false,
  "autoMemoryEnabled": false,
  "respondToBashCommands": false,
  "disableAutoMode": "disable",
  "useAutoModeDuringPlan": false,
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Bash(npm run build)"
    ]
  }
}

How to Reduce Claude Code's Initial Context and Avoid Prompt Cache Breaks

Fogel — Wed, 23 Sep 2026 09:24:30 +0000

Introduction

Lately, discussions around token optimization in Claude Code have focused primarily on skills, external tools, and optimizing CLAUDE.md. However, I noticed there is much less discussion about the massive savings you can achieve simply by configuring Claude Code's built-in settings correctly.

Curious about what the Claude Code harness actually adds behind the scenes, I decided to dive into its settings and environment variables. The results were much more interesting than I expected, which inspired me to write a series of articles on the topic.

In this article, I will break down the components of the Initial Context that Claude Code builds at the beginning of a new session. I'll analyze how many tokens these components consume and whether they dynamically change between sessions (which causes cache invalidation).

The goal of this article isn't to reduce the context to the absolute bare minimum. The goal is to remove data that is not useful for our work with Claude Code while preserving the capabilities we actually need for our workflow.

What is Initial Context?

The Initial Context is the foundational information that Claude Code adds at the beginning of a session. Part of it is sent as a top-level System Prompt within the system array, and another part is added immediately after the first user prompt inside the messages array.

The initial context consists of the following elements:

Inside the tools array:

Tools like Write, Read, Artifact, Glob, etc.

Inside the system array:

System prompts
Memory instructions

Inside the messages array:

CLAUDE.md
Git instructions
Deferred tools list (without schemas)
Built-in agents
Skills
Information from the IDE

The earlier a token appears in the conversation with Claude, the more expensive its cumulative cost becomes. This is because every new prompt we send to the model includes the Initial Context and the entire conversation history. Therefore, since the initial context accompanies us from the very first message, it has the highest cumulative impact on token consumption.

Furthermore, the more irrelevant text you feed into models, the more they tend to lose focus. The context should contain as much relevant information as possible, and as little irrelevant information as possible.

How does Prompt Caching work?

Every time you send a prompt to Claude, the entire context (initial context + conversation history) is sent along with it. Instead of reprocessing the same text over and over again, Claude can read previously processed text from its cache, process only the new text, and write that new text to the cache. This makes responses significantly faster and drastically reduces costs.

This mechanism relies on Prefix Matching: The model reads sequentially from the cache starting from the beginning of the prompt, until it reaches the first change in the text. The moment a single character changes in the middle of the context, all the information following it is no longer read from the cache - it is rewritten to the cache at full price.
Therefore, our goal is to keep the beginning of our context as static as possible and avoid dynamic content.

According to Claude's documentation, reading tokens from the cache costs a fraction of the base input token price. Currently, writing to a 1-hour cache costs 2x the base input token price, while a cache read costs at most 0.1x the base input token price.
For example, with Claude Opus 5, writing to a 1-hour cache costs $10 per million tokens, while reading from it costs only $0.50 per million tokens - a 20x price difference. Furthermore, in Claude Opus 5.5, this gap widens to a massive 40x price difference, and models like Claude Fable 5.1 push this gap to a significant 80x price difference!

Note: If we don't send a prompt to Claude within the defined cache TTL (5 minutes or 1 hour), the cache expires. The next time we send a message, the entire context will be rewritten to the cache from scratch instead of being read from it.

TL;DR

I found that Claude Code adds several components to the initial context that aren't necessarily needed for every task. By applying the configurations detailed in this article, I reduced the Initial Context from 35,011 tokens to 17,862 tokens (a ~49% reduction). Furthermore, the number of tokens forced to be rewritten to the cache in subsequent sessions dropped from 7,333 to 0.

Ultimately, you can decide which of these components are essential for your specific workflow with Claude Code.

Results by Component

Component	Added to Context	Cache Invalidation Risk
Artifact	11,403 tokens	Always breaks the cache
Git instructions	~500 tokens	Very High
Auto memory	738 tokens + `MEMORY.md` content	High
Skills	~2,100 tokens	Low
Claude Docs MCP	~1,701 tokens	None
IDE Integration	~100 tokens (manually removable)	None

Bonus: I also discovered how Claude Code's payload ordering breaks the cache on the very first prompt, and how starting every session with a generic "Hi" can save you ~65% on your initial prompt costs.

How were the tests performed?

To truly understand what Claude Code adds to the context, I intercepted and analyzed the network traffic of the API requests Claude Code makes when sending a message.
I mapped the tools, system, and messages arrays in the payload against the available configurations in settings.json and environment variables. For every overlapping setting, I compared the API request before and after the change, comparing both content and token count.

How did I measure the number of tokens?

I used two methods:

The /context command: Behind the scenes, this command triggers several API calls to count the number of input tokens for different parts of the system prompt and tools.
A Regular Prompt: I also sent a simple prompt ("hi") to trigger a full-context API call. The API response indicates exactly how many tokens were read from the cache and how many were written to it. In addition, I compared the context text sent before and after each configuration change to understand the specific setting's contribution to the session's context.

Test Environment

The tests presented in this article were performed using:

Claude Code version 2.1.278.
Model: Claude Opus 5 (unless otherwise specified).
A Claude subscription which, according to Claude Code documentation, utilizes a one-hour TTL cache.

Note: These results were measured in this specific environment. Initial context structure, token counts, and caching behavior may vary across Claude Code versions and models.
Also note that according to Claude's documentation, models from version 4.7 and above use a different tokenizer and consume up to 30% more tokens. Therefore, for Claude 4.7 and above, the quantitative token savings will be even more significant.

Deep Dive by Component

1. Artifact

Artifacts allow us to generate and share web pages via a private URL on claude.ai. For my own use cases, I don't need this feature, so I decided to test its impact on the Initial Context. It is enabled by default.

What does it add to the context?

Comparing the context with Artifact enabled vs. disabled revealed:

The Scratchpad Directory path is added to the system prompt in the messages array (222 tokens).
Artifact-specific skills and descriptions are added (which can also be viewed using /context all)
1. design (340 tokens)
2. artifact-design (70 tokens)
3. artifact-diagramming (70 tokens)
4. artifact-capabilities (220 tokens)
An Artifact tool is added (10,481 tokens). Total addition: 11,403 tokens.

Impact on Prompt Caching

The Scratchpad Directory path added to the system prompt in the messages array contains a unique Session ID. Because this ID changes between sessions, it alters the system prompt and guarantees a cache miss.

Therefore, I decided to measure the impact of that cache miss on the number of tokens that had to be written to the cache instead of read from it.

To prove this, I compared cache writes across four new, clean sessions, sending identical prompts:

Artifact Enabled: All tokens (34,724) were written to the cache (initial run).
Artifact Enabled: The system prompt changed because the directory name changed in the new session, breaking the prefix matching. 7,333 tokens were rewritten to the cache.
Artifact Disabled: The system prompt changed because the Artifact tool and Scratchpad Directory text were removed, causing a cache miss. 22,972 tokens were rewritten.
Artifact Disabled: The system prompt remained completely static, so there was no cache miss. 0 tokens were rewritten, everything was read from the cache.

Summary of disabling Artifact:

Saves 11,403 tokens on every single prompt.
Prevents guaranteed cache misses between sessions caused by content that changes in the system prompt. Converting a 7,333-token write into a read is particularly significant (remember the 20x to 80x price difference).

How to disable:

Add "enableArtifact": false to your global or project settings.json, or set the environment variable: CLAUDE_CODE_DISABLE_ARTIFACT=1.

2. Git Instructions

When working inside a Git repository, Claude Code adds your current Git status and recent commits into the system prompt in the messages array. This is enabled by default.

What does it add to the context?

I compared the context with Git instructions enabled vs. disabled.
It adds approximately 500 tokens to the system prompt.

Impact on Prompt Caching

Because the status of files in your working directory and your recent commits change frequently, this introduces a high risk of cache misses. I tested this by creating a new file and starting a new session - this caused 6,415 tokens to be rewritten to the cache.

Trade-offs

If disabled, Claude won't automatically know what branch you are on or what the current Git status is, unless it explicitly runs a git command to check.

My Recommendation

Since this is highly dynamic information and Claude Code can easily retrieve it using terminal commands when needed, it is better to avoid including it in the system prompt.

How to disable:

Add "includeGitInstructions": false to settings.json, either globally or at the project level. Another option is to set: CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1.

3. Auto Memory

Auto memory allows Claude to accumulate knowledge across sessions automatically without requiring manual input. It is enabled by default.

What does it add to the context?

Instructions for managing memory located in the system prompt (~738 tokens).
The actual content of the MEMORY.md file (Claude loads up to the first 200 lines or 25K, whichever comes first). Therefore, the actual number of tokens added by this component varies.

Impact on Prompt Caching

Because MEMORY.md gets updated, changes to this file between sessions will break the cache.

Ongoing Token Consumption During the Conversation

In addition, the act of Claude Code updating the auto-memory contents (MEMORY.md) during a conversation consumes additional tokens beyond those required to load the context.

Summary of disabling Auto Memory:

Saves 738 tokens from the system prompt.
Saves the tokens required for the first 200 lines or first 25K of MEMORY.md, whichever comes first.
Prevents cache invalidation caused by changes to MEMORY.md.
Prevents logical conflicts between Auto Memory and other information in the context, such as CLAUDE.md or our conversation history.

How to disable:

You can disable auto memory using /memory, or add "autoMemoryEnabled": false to the global settings.json, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
See the Claude Code memory documentation

4. Skills

Disabling Skill Auto-Invocation

When a new skill is added, its name and description are added to the context. A skill can be triggered in two ways:

Claude decides to use it based on its description (Auto-invocation).
The user explicitly invokes the skill using /skill-name.

You can disable auto-invocation (the first way). If you do, the skill's description is removed from the initial context, saving tokens, but you will have to call it manually using /skill-name.

Here are several ways to disable auto-invocation:

Specific skill: Add disable-model-invocation: true to the skill's frontmatter.
All project skills: Use the skillOverrides setting. Use it for skills whose SKILL.md you don’t want to edit, like skills you didn't write yourself. (Note: this doesn't affect plugin skills. Plugin skills must be managed using /plugin).
All skills (including plugins): A clever workaround to prevent auto-invocation for all skills, including plugin skills, is using the setting "skillListingMaxDescChars": 1. This truncates all descriptions, saving at least ~2,000 tokens when including the built-in skills.

Disabling Built-in Skills

Claude Code includes several built-in skills (like keybindings-help or claude-api) that you might rarely use.
The full list of built-in skills can be viewed using: /context all.

Context addition: Names and descriptions of bundled skills add about 2,134 tokens.
How to disable: Add "disableBundledSkills": true to settings.json. (Note: This completely removes them, meaning you cannot invoke them manually either).

5. Claude Docs MCP

This is a connector that links to Claude Docs on claude.ai. It allows Claude to create, read, edit, comment on, and export documents stored in your claude.ai account. They're not files in your repository.

What does it add to the context?

Instructions on how to use its tools and resources, located in the system prompt in the messages array (~1,031 tokens).
The MCP tools of Claude Docs are loaded (which can also be viewed using /context all)
1. mcp__claude_ai_Claude_Docs__batch (163 tokens)
2. mcp__claude_ai_Claude_Docs__guide (212 tokens)
3. mcp__claude_ai_Claude_Docs__update (295 tokens)

It adds approximately 1,701 tokens to the context.

Impact on Prompt Caching

It doesn't affect prompt caching.

My Recommendation

Since I don't see a reason to use this within Claude Code, I prefer to disable it.

How to disable

Run /mcp, select "claude.ai Claude Docs" and disable it.
Alternatively, remove or disconnect the connector in your claude.ai settings under Connectors. That affects every client using your account, not just Claude Code.

I'd recommend disabling it via /mcp if you only want to turn it off for Claude Code.

6. IDE Integration

If you run Claude Code inside an IDE terminal (like VS Code), it automatically connects to the IDE.
Personally, I often have a file open in the IDE (sometimes with text selected) that is completely unrelated to what I'm asking Claude to do in the terminal.
In that situation, the IDE adds the text [⧉ In filename.ext] or [⧉ X lines selected] to the beginning of the terminal prompt line, even though it may not be relevant to the current conversation.
This increases token consumption, can reduce the model's focus, and may even lead to incorrect answers.
You can easily remove it with backspace, just as you would with any other part of the prompt.

What does it add to the context?

The name of the currently active file in the IDE (Adds ~100 tokens). You can remove it manually from the prompt.
Currently selected lines of the open file in the IDE (Adds a dynamic token count).
Errors showing in the IDE's "Problems" tab (Adds dynamic token count).

Impact on Prompt Caching

Because it is added to the end of the context, it doesn't affect prompt caching.

My Recommendation

I personally prefer that Claude does not automatically consider whichever file happens to be open in my IDE, so I disable the "Attach Open File" setting.

How to disable:

You can prevent Claude Code from adding the currently open file in the editor by disabling the Attach Open File setting in your VSCode settings. When disabled, only the text you actively select is added.

You can also open VS Code settings (Cmd+, on Mac or Ctrl+, on Windows/Linux), go to Extensions -> Claude Code, and uncheck Attach Open File.

Extra Insight: The First Prompt Cache Trap

While analyzing the API payloads, I noticed something interesting: there is a specific System Prompt block that is not sent as part of the system array. Instead, it is added to the messages array immediately after the user's first prompt.

This added System Prompt block contains:

Claude Code CLI Environment
The deferred tools list
Built-in agents
Skills list
IDE integration data

Because Prompt Caching relies on Prefix Matching (matching from the start of the text until the first change), sending a different first prompt in a new session breaks the sequence immediately.
As a result, that entire massive system block added after your first prompt is treated as "new" text and is written to the cache at the 20x to 80x price!

I tested two sequential sessions (with Artifact disabled, as it always breaks prompt caching):

Scenario	Cache Read	Cache Write
Two sessions with the same first prompt	23,978 tokens	0 tokens
Two sessions with a different first prompt	17,566 tokens	6,412 tokens

As you can see, changing your first prompt causes Claude to rewrite 6,412 tokens of the system prompt to the cache.

The Practical Workaround: The Static "Hi"

To prevent this cache break, I tested a workflow where I open every new session with a static prompt (e.g., "Hi"). Once Claude responds, I send my actual prompt.

I compared the costs of asking "What model are you using?" in two scenarios:

Scenario A: Sending the question (actual prompt) directly as the first prompt

Action	Cache Read	Cache Write	Total Cost
Prompt 1: "What model are you using?"	17,566	6,416	$0.072943

Scenario B: Starting with a Fixed First Prompt ("Hi"), then asking the question (actual prompt)

Action	Cache Read	Cache Write	Total Cost
Prompt 1: "Hi"	23,978	0	$0.011989
Prompt 2: "What model are you using?"	23,978	146	$0.013449
Total	47,956	146	$0.025438

Conclusion:
Even though Scenario B required two API calls and processed double the total tokens, the overall cost dropped by 65%. We successfully converted an expensive cache write into a cheap cache read.

Note: This workaround only saves money if you are starting a new session within 1 hour of your previous prompt. If your cache has completely expired, you will pay for a full rewrite regardless, so you might as well send your actual prompt first (in our example: "What model are you using?").

Conclusion

The goal of this optimization is to achieve a context window that only contains data actively contributing to the current session, while keeping that data as static as possible to maximize prompt caching.

By understanding the API payload structure and tweaking Claude Code's settings, we achieved four major goals:

Token savings: Reduced the initial context from 35,011 to 17,862 tokens, a 49% drop.
Prompt cache stability: Eliminated dynamic text in the initial context (like the Scratchpad path) that breaks prefix matching and causes cache misses, dropping token rewrites from 7,333 to 0.
Model focus: Removed irrelevant background information (like randomly opened IDE files), allowing Claude to focus entirely on the actual prompt.
Workaround for the first prompt cache trap: Understanding that a system prompt block containing skills and other metadata is inserted after the first user prompt inside the messages array allows us to use a fixed opening prompt (such as "Hi"). This saves approximately 65% on the cost of the initial prompt in sessions where the previous session occurred within the last hour.

Every developer should decide which of these components are worth their token cost.

Here is a summary of the settings discussed in this article:

// ~/.claude/settings.json or .claude/settings.json in your project
{
  "env": {
    "CLAUDE_CODE_DISABLE_ARTIFACT": "1",
    "CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS": "1",
    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"
  },
  "disableBundledSkills": true,
  "skillListingMaxDescChars": 1
}

Disabling Claude Docs MCP: Run /mcp, select "claude.ai Claude Docs" and disable it.

In the next article, we will focus on workflows and configurations to save tokens during active, ongoing conversations, rather than just the initial context. Stay tuned!

Potential issues with barrel files in Jest

Fogel — Wed, 22 May 2024 09:02:23 +0000

Introduction

In the previous article, Potential issues with barrel files in Webpack, we discussed the potential issues of using barrel files in Webpack. In this article, we will focus on the issues of using them in Jest tests.

For a comprehensive understanding of barrel files and their use cases, I recommend reading the previous article.

Barrel files in Jest

Unlike Webpack, Jest does not have a tree shaking feature. This means that when you import modules through barrel files, Jest will include all the exported modules from barrel files in your tests, even those that are not used. This behavior can lead to two significant issues: slow performance and unexpected test results.

Issues

1. Performance Impact

One of the most common complaints from developers who use Jest often report slow test execution times when their code includes barrel files #1. While this might not be noticeable in smaller projects, it becomes a significant issue in larger ones.

This issue arises because Jest needs to load all the modules exported from a barrel file, regardless of their usage. This can significantly increase loading time, especially if the barrel file contains numerous modules.

Example

To illustrate this issue, let's consider the perf-impact example repository.
In this repository, we want to test the Javascript file indirect-import.js that imports only the Reexported1 specifier from a barrel file index.js, which re-exports 100 modules.

Let's create a test for this file named indirect-import.test.js and run npm run test and observe the performance.

The test execution takes an average of 2.865 seconds, which is significant for a single test. Imagine the time it would take for hundreds of tests relying on barrel files!

Why is it slow? When importing from barrel files, Jest loads all the modules, even unused ones, impacting performance.
We need a solution for this poor test performance.

Solution

One solution could be to avoid using barrel files altogether, but this would negatively impact our developer experience.

Another solution can be using a tool that will automatically transform indirect imports to direct imports.
To address this, I developed a Babel plugin, babel-plugin-transform-barrels, that transforms indirect imports (through barrel files) into direct imports.

Let's apply the babel-plugin-transform-barrels plugin solution as follows:

Clone the perf-impact repository to a new perf-impact-with-barrel-plugin repository.
Install the babel-plugin-transform-barrels plugin.
Copy the babelTransform.js file into the folder config\jest.
Adapt the babelTransform.js file to the current repository.
In the jest.config.js file, reference the transform object to the babelTransform.js file instead of the regularTransform.js file.
Run the command npm run test.

Now, see that the test time dropped from 2.865 seconds to 1.31 seconds, which is a reduction of more than 50%. This improvement is very significant!

Note
The above steps have been implemented in the perf-impact-with-barrel-plugin repository.

Now that we’ve addressed the performance issue, let’s move on to the next issue.

2. Unexpected Test Results

Another issue can arise when we import a module from a barrel file that contains unused modules, some of these unused modules can affect the test results in unexpected ways.

Example

To illustrate this issue, let's consider the unexpected-results example repository.
In this repository, we want to test the Javascript file indirect-import.js that imports only FirstReexported specifier from a barrel file index.js, which re-exports all the specifiers from the Reexported and DropFiles modules.

Let's create a test for this Javascript file named indirect-import.test.js and run npm run test.

We can see that the test failed. As we can see in the details of the test's result, the failure is caused by the module DropFiles.

But why did the test fail because of an unused module that we didn't want to import? As mentioned earlier, when we import from a barrel file, all the re-exported modules will be loaded, even the unused modules.

Again, the barrel file caused a problem for us!

Solution

The solution here is the same as the previous example of perf-impact. We need to transform the imports from indirect imports (through barrel files) to direct imports.

Let's do the same steps as the previous example.

Let's apply the babel-plugin-transform-barrels plugin solution as follows:

Clone the unexpected-results repository to a new unexpected-results-with-barrel-plugin repository.
Install the babel-plugin-transform-barrels plugin.
Copy the babelTransform.js file into the folder config\jest.
Adapt the babelTransform.js file to the current repository.
In the jest.config.js file, reference the transform object to the babelTransform.js file instead of the regularTransform.js file.
Run the command npm run test.

Now we can see that the test passes successfully!

Note
The above steps have been implemented in the unexpected-results-with-barrel-plugin repository.

Summary

While using barrel files can offer benefits for developer experience, it can also lead to performance issues and unexpected test results in Jest. To resolve them, use the babel-plugin-transform-barrels plugin, which transforms indirect imports (through barrel files) into direct imports.

This plugin effectively maintains developer experience with test performance and reliability.

I hope this article has provided you a deeper understanding of the issues with using barrel files in Jest and how the babel-plugin-transform-barrels can be a valuable tool in your testing toolkit.

Boost Your Webpage Load Performance with the new Webpack plugin

Fogel — Thu, 05 Oct 2023 13:50:28 +0000

Introduction

A website’s initial loading speed can significantly impact user experience and SEO. Slow loading times can bother many users.
To address this issue, I’ve developed a new Webpack plugin called html-webpack-preload-react-router. This plugin improves the initial loading speed of a website by reading the react router plain objects and then preloading only the essential async chunk files and performing data fetching. All of that occurs in parallel during the initial load.

Background

When using react router with code splitting (lazy loading) the process of loading a website is:

Downloading and executing the initial HTML file.
The HTML fetches and executes only the initial Javascripts and CSS chunks.
The react router code examines the current URL path and runs loader method if defined.
The react router code examines the current URL path and fetching and executing only the relevant chunk files based on element property.

Each step involves a network request and happens sequentially. It is a waste of time! In this article we show a solution that 2nd, 3rd and 4th steps will be parallelized network requests, which significantly reducing loading times and improving user experience.

A regular initial webpage loading example

Before I show the solution I want to show through a basic example the network waterwall of the traditional react webpage like we described in the Background section.

In this example, the Products component is code splitted through lazy loading.

products.route.js

//...
const Products = lazy(() =>
  import(/* webpackChunkName: 'Products' */ "./Products")
);
//...

So Let's see in DevTools the network waterwall when we navigate to https://regular-81820.web.app/products.

We see that there are 4 network requests in a row and this we want to parallelize as much as possible.

The solution

After I read the great article by Almog Gabay on Client-Side Rendering (CSR), particularly the Preloading Async pages section, I tought to myself why not using react router plain objects for another purposes like preloading with help from Webpack? The idea was to have a single array of plain objects serving multiple purposes - routing and preloading. After experimenting with various edge cases, I successfully created a stable Webpack plugin. This plugin generates an HTML file that handles preloading of async chunk files derived from React Router’s plain objects and also preloads data from the database (this feature is currently limited to GET requests).

A new webpack plugin - html-webpack-preload-react-router

The plugin html-webpack-preload-react-router is easy to install and setup. It gets as an argument the path for the entry route of the website.
In each object of react router plain objects we need to give the chunk name in a property called chunkName. The value needs to be the same value of the magic comment webpackChunkName of import().
In addition, because we make a fetching from database, we can preload also the data by configure the property data.
It will be easier to understand throughout an example.

A preloading initial webpage loading example

Let's use the same website example of A regular initial webpage loading example.
And do the following steps:

Install the plugin.

npm install --save-dev html-webpack-preload-react-router

Configure the webpack.config.js file:

webpack.config.js

   const HtmlWebpackPlugin = require("html-webpack-plugin");
+  const ReactRouterPreloadChunksPlugin = require("html-webpack-preload-react-router");
+  const entryRouteFilename = path.resolve(`./src/pages/entryRoute.route.js`);
   module.exports = {
      //...
      plugins: [
         new MiniCssExtractPlugin(),
         //...
+        new ReactRouterPreloadChunksPlugin({
+           entryRoute: entryRouteFilename,
+        }),
      ]
      //...
   };

Add chunkName property for each object in the routing of react router plain objects.

products.route.js

   export const productsRoutes = [
     {
       path: "",
+      chunkName: "Products",
       id: "products",
       loader: () => fetch("https://dummyjson.com/products").then((res) => res.json()),
       element: <Products />,
       children: [
         {
           path: ":productid",
+          chunkName: "Product",
           element: <Product />,
         },
       ],
     },
   ];

Add data property for each object in the routing of react router plain objects that fetch a data.

products.route.js

   export const productsRoutes = [
     {
       path: "",
       chunkName: "Products",
       id: "products",
       loader: () =>
         fetch("https://dummyjson.com/products").then((res) => res.json()),
       element: <Products />,
       children: [
         {
           path: ":productid",
           chunkName: "Product",
           element: <Product />,
         },
       ],
+      data: {
+        url: "https://dummyjson.com/products",
+        crossorigin: "anonymous",
+      },
     },
   ];

So let's see in DevTools the network waterwall when navigating to https://preloading-ea687.web.app/products:

Now we can see in the DevTools that there are 2 network group requests (instead 4 in a row), each group has network requests in parallel (first is products and second are main.9aa6dd.js, Products.023320.js and products in parallel). This is because the HTML is using preloading for async chunk files according to the URL path. It improves our website's performance!

Bonus - Navigation bar

After we saw that we can use react router plain objects for 2 purposes of routing and preloading, I found a third purpose of using - navigation bar.
In each object of the react router plain objects we need to give the link text in a property called linkText.

It will be easier to understand throughout an example.

A navigation bar example

Let's use the same website example of A preloading initial webpage loading example.
And do the following steps:

Change the react router plain objects entryRoute:

entryRoute.route.js

   export const entryRoute = [
     {
       path: "",
       element: <Layout />,
+      id: "links",
+      loader: () => entryRoute[0].children,
       //...
     },
   ];

Change the Layout component for reading link texts from the react router plain objects entryRoute:

Layout.js

   //...
   function Layout() {
+    let links = useRouteLoaderData("links");
     return (
       <nav>
         <ul>
-          <li>
-            <Link to="/">Home</Link>
-          </li>
-          <li>
-            <Link to="/about">About</Link>
-          </li>
-          <li>
-            <Link to="/products">Products</Link>
-          </li>
+          {links.map((link) => {
+            return (
+              <li>
+                <Link to={link.path?.replace("/*", "")}>{link.linkText}</Link>
+              </li>
+            );
+          })}
         </ul>
       </nav>
       //...
     );  
   }

Now we can see that the navigation bar works the same but use the data from react router plain objects. It is easier to maintain a single source of truth rather than 3 different sources.

Summary

In this article, we tried a new webpack plugin html-webpack-preload-react-router , which collaborates seamlessly with React Router’s plain objects. It generates a production html file that preloads async chunk files and fetched data based on the current URL path. It parallelizes network requests, which makes our webpage load faster! Additionally, React Router’s plain objects can be utilized for the navigation bar.

In short, now we can use the react router plain objects as a single source of truth for 3 purposes:

Routing.
Preloading async chunk files and fetched data from database (GET requests).
Navigation.

It makes our website's code easy to understand and maintained and improve the performance of initial loading webpages in our website.

I hope you enjoyed to read my article and hope you will try my new Webpack plugin html-webpack-preload-react-router.

Potential issues with barrel files in Webpack

Fogel — Tue, 18 Jul 2023 12:09:37 +0000

Introduction

Barrel files make the development more convenient, but how do they impact the bundle files generated by Webpack?

In this article, we will discuss the question above. I will demonstrate how to configure Webpack to work with barrel files and dynamic import and how it's recommended to create modules. As incorrect config of Webpack can lead to different issues, some of them being performance issues as a result of unused code and others being visual issues.

We will examine several solutions and go through a process together to find the optimal solution.

This article assumes familiarity with optimization configuration of Webpack. Therefore, If you're new to this topic, I recommend reading my previous article on Tree shaking in Webpack before continuing reading this article.

TL;DR

If you utilize barrel files with code splitting and employ regular CSS imports in your projects, I highly recommend using the babel-plugin-transform-barrels plugin instead of manually configuring sideEffects. This plugin will help prevent unexpected visual issues on your webpage and effectively reduce the size of your bundle files.

Furthermore, if code splitting is part of your development approach, I suggest creating modules with only one export each, whenever possible. This practice significantly decreases the size of your bundle files.

Additionally, for code splitting scenarios, I highly recommend leveraging the splitChunks configuration as explained in this article. This configuration allows for the elimination of duplicate code of common modules found in different chunks and will create a common chunk for common modules, resulting in optimized bundle files.

What are barrel files (index.js)?

Before we dive into the issues and because most of them were caused by barrel files, I want to explain what barrel files are and their appropriate use cases. I will focus on the advantages, but you can learn more about their advantages and disadvantages in the Additional Resources section below.

A barrel is a file that re-exports other modules' exports into a single file. In my opinion, it is better to use one level of barrel files in the folder structure. It's not recommended to create a barrel file for every folder.

Developers use barrel files (index.js) for the following development purposes:

It makes the code more readable by shortening import path and decreasing the number of lines of code.

Example

Without barrel files

import { Button } from './components/Button/Button'
import { Avatar } from './components/Avatar/Avatar'
import { List } from './components/List/List'

With barrel files

import { Button, Avatar, List } from './components'

When creating a third-party library and wanting to make specific functions public for consumers.

The following quote from yuchant on Github issue provides a good explanation:

Barrel files are effectively an API. A specific interface that distinguishes private vs public code.
Changes in the module's internal structure don't affect the library's consumers.

Additional Resources:

Are TypeScript Barrel Files an Anti-pattern?

Barrel files in Webpack

After we have seen the advantages of using barrel files and how they improve our developer experience, now we will see their usage and how they affect the bundle files.

As we have already learned in the previous article about Tree shaking in Webpack, when there is no use of optimization, every module and its dependencies that exist in the code will be included in bundle files. So when we import a barrel file module, all the re-exported modules included inside it will be included in the bundle files, even modules that are not in use. This will increase the size of the bundle files and consequently harm performance.

Optimization properties

Because barrel files can increase dramatically our bundle files size, we will use barrel files with usedExports and sideEffects optimization properties to eliminate unused code. Therefore in our example, modules in barrel files whose exports are not used will not be included in the final bundle files.

First, let's look at the main files of the example:

webpack.config.js

const MiniCssExtractPlugin = require("mini-css-extract-plugin");
//...
module.exports = {
  mode: "development",
  optimization: {
    usedExports: true,
    sideEffects: true,
  },
  module: {
    rules: [
      {
        test: /\.css$/,
        exclude: /node_modules/,
        use: [MiniCssExtractPlugin.loader, "css-loader"],
      },
      //...
    ]
  },
//...
}

App.js

import GreenSection from "./components/Sections/GreenSection/GreenSection";
import RedSection from "./components/Sections/RedSection/RedSection";
import { BlueStrong } from "./components/Strongs";

function App() {
  return (
    <>
      <BlueStrong>Blue strong component (Direct Import)</BlueStrong>
      <hr />
      <GreenSection />
      <hr />
      <RedSection />
    </>
  );
}

export default App;

GreenSection.js

import { GreenText } from "../../Texts";
import { GreenButton } from "../../Buttons/GreenButton/GreenButton";
import { getTenNumber } from "../../../tools/numberFunctions/numberFunctions";

function GreenSection() {
  const tenNum = getTenNumber();
  return (
    <>
      <GreenText>Green text component (Indirect import - Barrel)</GreenText>
      <GreenText>Green ten number: {tenNum}</GreenText>
      <GreenButton>Green button component (Direct import)</GreenButton>
    </>
  );
}

export default GreenSection;

RedSection.js

import { RedText } from "../../Texts";
import { RedButton } from "../../Buttons/RedButton/RedButton";
import { getThousandNumber } from "../../../tools/numberFunctions/numberFunctions";

function RedSection() {
  const thousandNum = getThousandNumber();
  return (
    <>
      <RedText>Red text component (Indirect import - Barrel)</RedText>
      <RedText>Red thousand number: {thousandNum}</RedText>
      <RedButton>Red button component (Direct import)</RedButton>
    </>
  );
}

export default RedSection;

Before we bundle our example, let's briefly review the code above and especially the imported modules.

Let's take a look at App.js, we can see that three components are in use: BlueStrong, GreenSection and RedSection.

GreenSection.js and RedSection.js modules are performing module imports according to the appropriate color from subdirectories of Buttons and Texts, as well as importing a module numberFunctions.js.

The only module that we will import indirectly from a barrel file will be from Texts. The remaining modules will be imported directly as we have always done.

Each appropriate module of color inside the subdirectories of Buttons, Strongs and Texts has imported also a CSS file for each.

After we did a short brief about how the code is implemented, we will describe in short what we expect to see in the rendered webpage. The first line should be in the blue color, 2-4 lines should be in green color and 5-7 lines should be in red color.

We can see in the webpack.config.js file, that there is a rule about CSS files that use the loader of mini-css-extract-plugin, so each time Webpack parse the CSS files it process the loader and will inject the content of the CSS files into chunk file. In our example it will be main.css.

During the bundling process, we expect that it will produce two files (JS and CSS files).

Now run npx webpack in the terminal window.

The build process created two files as expected: main.js and main.css.

Let's take a look at the browser and check the rendered page:

The page was rendered as expected.

Now let's analyze the bundle files.

It would be easier to understand if we organized all bundle files in a table according to the following columns:

Bundle file name.
List of modules that combined to the bundle file. It's after sideEffects optimization effect.
The included functions (Actual) inside the bundle file. It's after usedExports optimization effect.
The functions that the bundle file should include (Expected) for the most optimized desired bundle file.

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, Button.js, GreenButton.js, RedButton.js, GreenSection.js, RedSection.js, BlueStrong.js, Strong.js, Texts/index.js, GreenText.js, RedText.js, Text.js, numberFunctions.js	App, Button, GreenButton, RedButton, GreenSection, RedSection, BlueStrong, Strong, GreenText, RedText, Text, getTenNumber, getThousandNumber	App, Button, GreenButton, RedButton, GreenSection, RedSection, BlueStrong, Strong, GreenText, RedText, Text, getTenNumber, getThousandNumber

Let's take a look in the JS bundle file:

main.js

//...
/* unused harmony export getHundredNumber */
function getTenNumber() {
  return 10;
}
function getHundredNumber() {
  return 100;
}
function getThousandNumber() {
  return 1000;
}
//...

In the main.js file, we can see that Webpack bundled all the used functions, including the unused getHundredNumber function, which is marked as an unused harmony export by the usedExports property. Note that the RedText component is imported from "Texts/index.js", which is a barrel file, so all re-exported modules of the barrel file should be included, such as the BlueText module. But because we use the sideEffects property and the BlueText module is not used and doesn't have side effects, it is excluded from the bundled file.

Let's analyze the CSS bundle files:

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	Text, RedText, BlueText, GreenText, Button, GreenButton, RedButton, Strong, BlueStrong	Text, RedText, GreenText, Button, GreenButton, RedButton, Strong, BlueStrong

In the main.css file, we can see an unused class selector for .BlueText because we imported a barrel file module that includes the unused BlueText module. While the BlueText module was being evaluated, the BlueText.css file was extracted by the mini-css-extract-plugin plugin and added to the main.css file. Afterwards, BlueText was eliminated from main.js due to the sideEffects: true property. We will continue to monitor this unnecessary CSS selector. Note that unnecessary CSS selectors only come from unused modules that are re-exported in used barrel files. For example, there is no .BlueButton CSS selector because GreenButton and RedButton are directly imported rather than through a barrel file.

So we have an issue that we want to solve: we don't want the unnecessary .BlueText CSS selector and we want our JS and CSS to be as small as possible.

We have two ways to solve it:

Change the imports of the GreenText and RedText to be direct imports instead of indirect imports (index.js - barrel file), so this will prevent the BlueText module and its CSS file from being loaded. This is similar to why the .BlueButton CSS selector is not present in the CSS file because GreenButton and RedButton are directly imported.
Since the BlueText.js module has an unused export and our project only has side effects in CSS files, we can manually define which modules have side effects using the config option sideEffects: ["*.css"] and then the remaining modules with unused exports like BlueText.js will be flagged as having no side effects. This will prevent evaluation of the BlueText.js module and extraction of its CSS file content through the loader.

Dynamic import (Lazy loading in React)

After we saw that using barrel files can cause unused CSS files content to be included in CSS bundle file and we disscused the optional solutions, now I want to check the using barrel files inside a module that dynamically imported.

Dynamic import of a module is usually used when we want to load the module in specific conditions (inside if statement or event handler). If these conditions are not met, the code inside this module will not be evaluated, so we don't really need to download this module while the conditions are not met. So here Webpack comes to help. Webpack will create a bundle file for each module that is dynamically imported and for its dependencies and only download and evaluate this module when the conditions are met.

For example, in React there is a package named react-router-dom that allows render specific components for a specific URL path and render different components for a different URL path. In this case, it's recommended to use in lazy loading to make the components' modules downloaded from the server only when they are used. To make it happen, Webpack will create a new bundle file for each lazy loaded module with its dependencies.

As described in Webpack website:

Dynamically load modules. Calls to import() are treated as split points, meaning the requested module and its children are split out into a separate chunk.

Dynamic import in Webpack is important for improving performance of initial loading because it allows us to only download and evaluate what is needed on each webpage. This means we can include in the bundle file only the necessary modules for the initial loading and as a result make smaller bundle file that then make our webpage load faster.

For our example, and to keep it simple, we will change only the imports of RedSection.js and GreenSection.js to be dynamic imports without conditionally use them so both of them always will be downloaded in the initial loading of the webpage. We expect that Webpack will create three JS bundle files instead one.

As we remember, RedSection.js and GreenSection.js modules have two direct common modules: Texts/index.js and numberFunctions.js that uses different functions inside them. How webpack will handle it? Are the common modules will be included only in both bundle files? Or maybe only in the main bundle file? Or maybe a fourth bundle file will be created for common modules? The answer we will see after the bundling process of the example.

Let's create an example and see the files it produces.

Clone the previous 1-optimization-sideEffects example into a new 2-lazy-loading example and make the following changes to the App.js file:

App.js

- import GreenSection from "./components/Sections/GreenSection/GreenSection";
- import RedSection from "./components/Sections/RedSection/RedSection";
  import { BlueStrong } from "./components/Strongs/BlueStrong/BlueStrong";
+ import { lazy, Suspense } from "react";

+ const GreenSection = lazy(() => import(/* webpackChunkName: 'GreenSection' */ "./components/Sections/GreenSection/GreenSection"));
+ const RedSection = lazy(() => import(/* webpackChunkName: 'RedSection' */ "./components/Sections/RedSection/RedSection"));

  function App() {
    return (
      <>
+       <Suspense fallback={<></>}>
            <BlueStrong>Blue strong component (Direct Import)</BlueStrong>
            <hr />
            <GreenSection />
            <hr />
            <RedSection />
+       </Suspense>
      </>
    );
  }

  export default App;

Now run npx webpack in the terminal window.

This produces the following files:

main.js and main.css.
GreenSection.js and GreenSection.css - New files.
RedSection.js and RedSection.css - New files.

Let's take a look at the rendered page in the browser:

We see that the Green button component (direct import), which is part of the GreenSection, has turned black instead of being green. Why did this happen?

First, let's take a look at the DevTools:

We can see that the .Button CSS selector appears twice. The GreenSection.css file loads both .Button and .GreenButton, but then .Button is loaded again but from the RedSection.css file. Loading the .Button CSS selector only once from GreenSection.css file will solve this problem. This happens because the Button.js module loaded twice instead of once, causing it to override the green color with black. The order in which CSS properties (in our case color) are applied is determined by their order of loading, where properties from class selectors loaded later will override those from earlier class selectors.

Now let's analyze our bundle files.

It would be easier to understand if we organized all bundle files in a table according to the following columns:

Bundle file name.
List of modules that combined to the bundle file. It's after sideEffects optimization effect.
The included functions (Actual) inside the bundle file. It's after usedExports optimization effect.
The functions that the bundle file should include (Expected) for the most optimized desired bundle file.

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	Button.js, GreenButton.js, GreenSection.js, GreenText.js, RedText.js, Text.js, Texts/index.js, numberFunctions.js	Button, GreenButton, GreenSection, GreenText, RedText, Text, getTenNumber, getThousandNumber	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	Button.js, RedButton.js, RedSection.js, GreenText.js, RedText.js, Text.js, Texts/index.js, numberFunctions.js	Button, RedButton, RedSection, GreenText, RedText, Text, getTenNumber, getThousandNumber	RedText, RedButton, RedSection, getThousandNumber
*common.js			Text, Button

Note: The common.js is not produced by the build process. It's my suggestion for a bundle file for functions that are used by more than one JS bundle file.

Explanation of JS bundle files

First, we will check in what bundle files the common modules Texts/index.js and numberFunctions.js of GreenSection.js and RedSection.js source files are included. It can be seen in the table above that they are included inside RedSection.js and GreenSection.js bundle files. We expected that the usedExports and sideEffects optimization properties would eliminate the unused code separately in each RedSection.js and GreenSection.js bundle files. Unfortunately Webpack doesn't do that. We can see in both bundle files that the content of the imported modules are the same to the first example where only BlueText.js module and getHundredNumber function are eliminated. Unfortunately, the usedExports and sideEffects optimizations performed on the entire code are the same as in the first example without dynamic imports. Therefore, the RedSection.js bundle file will include also the unused GreenText.js module and getTenNumber function and the GreenSection.js bundle file will include also the unused RedText.js module and getThousandNumber function. The Texts/index.js and numberFunctions.js modules have different solutions. For Texts/index.js, we can use the same solution I suggested in the first example. For numberFunctions.js, we can use the solution of separating the module to 3 different modules that each one will have one function and then import the function from his specific module.
In addition, Text.js and Button.js are indirectly common modules imported from Texts/index.js, GreenButton.js and RedButton.js modules. Therefore, Text.js and Button.js modules content appear in both GreenSection.js and RedSection.js bundle files that uses the same functions (Text and Button functions). This results a duplicate code, and our goal is to reduce their size. To solve this issue, we should try creating a separate bundle file for common modules which have the same used functions of both sections. Since Text.js and Button.js are modules with one function each, we can conclude that both sections are using the same functions from these modules.

Let's analyze the CSS bundle files.

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	Text, RedText, BlueText, GreenText, Button, GreenButton	GreenText, GreenButton
RedSection.css	Text, RedText, BlueText, GreenText, Button, RedButton	RedText, RedButton
common.css		Text, Button

Explanation of CSS bundle files:

The main.css file has class selectors for .Strong and .BlueStrong because we use the BlueStrong component in the App.js file and it works as expected.
In the CSS bundle files of GreenSection.css and RedSection.css modules, we can see that the .BlueText CSS class selector appears even when the BlueText component isn't used. We already talked about the reason why it happened in the first example and that there are two ways to solve it and we will try these options later.
The .GreenText appears in RedSection.css and .RedText appears in GreenSection.css, even though both of them aren't useful and need to be eliminated. It happened because their modules (GreenText.js and RedText.js) are imported from the barrel file of Texts/index.js. Later we will see if the solution for .BlueText will help us solve this issue as well.

Let's summarize the issues for the example of lazy loading:

Green button component (direct import) button has a black color instead green.
getTenNumber and getThousandNumber functions exist in both GreenSection.js and RedSection.js bundle files instead, getTenNumber should only be included in GreenSection.js and getThousandNumber should only be included in RedSection.js. The same applies to the unused RedText in the GreenSection.js bundle file and the unused GreenText in the RedSection.js bundle file. Why did this happen? Because the optimizations of usedExports and sideEffects occurred to the entire code and not separately to each bundle file.
Text.js and Button.js modules appear in two bundle files of GreenSection.js and RedSection.js instead of in one common bundle file for both sections.
.BlueText exists in both bundle CSS files even though it is unused. .RedText should be eliminated from GreenSection.css bundle file and .GreenText should be eliminated from RedSection.css bundle file.

Splitting bundle files can cause new issues. Some of these issues can affect performance, while others can cause unexpected visual issues that are more critical because they affect the user experience. So first, let's try to fix style issues and unnecessary duplicate code by using the optimization configuration of the splitChunks property. After that, we will address unused functions and CSS selectors to decrease the size of bundle files.

Create a separate bundle file for common modules

In the previous chapter on dynamic import, we saw that each dynamic import in Webpack produces JS and CSS bundle files. In addition, commonly used modules exist in all bundle files that use these modules. As a result, there are CSS classes that are loaded twice and also duplicate Javascript code. This behavior causes four issues, one of which is an unexpected visual issue.

To address this, we can use the splitChunks property to create a bundle file of common modules.

Let's clone the previous example 2-lazy-loading to 3-splitChunks and change the Webpack config file as follows:

webpack.config.js

//...
module.exports = {
  mode: "development",
  optimization: {
    usedExports: true,
    sideEffects: true,
+   splitChunks: {
+     cacheGroups: {
+       default: false,
+       defaultVendors: false,
+       src: {
+     test: /[\\/]src[\\/]/,
+     minSize: 0,
+     priority: 100,
+     name: (module, chunks) => {
+       const allChunksNames = chunks.map(({ name }) => name).join(".");
+       return `${allChunksNames}`;
+     },
+     chunks: "all",
+   },
+     },
+   },
  },
//...
}

Let's briefly explain what splitChunks is doing with the configuration above. It traverses each module that includes the src directory in its path and assigns a bundle file name to each traversed module through the name property. The bundle file name of the traversed module will be the name of the chunk names (webpackChunkName magic comment inside import() statement) of dynamically imported modules that include this traversed module. For example the module numberFunctions.js is included in GreenSection.js and RedSection.js source files that are dynamically imported, so the bundle file name that the module numberFunctions.js should be inside is GreenSection.RedSection.js.

I think my configuration above is better than the configuration described in the article webpack 4: Code Splitting, chunk graph and the splitChunks optimization because I control the name of the bundle files to be the name of the dynamically imported modules.

Now run npx webpack in the terminal window.

It produces the following files:

main.js and main.css.
GreenSection.js and GreenSection.css.
RedSection.js and RedSection.css.
GreenSection.RedSection.js and GreenSection.RedSection.css - New files.

In comparison to the previous example 2-lazy-loading, it generated GreenSection.RedSection.js and GreenSection.RedSection.css bundle files in addition.

Now let's take a look in the browser and check the rendered page:

We see that the Green button component (direct import) is rendered with the green color as expected.

Let's inspect the button element:

We can see that the .Button CSS selector now appears only once in the common bundle file GreenSection.RedSection.css, so with the splitChunks property, we have finally solved this visual issue.

Let's analyze the bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js	GreenButton, GreenSection	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js	RedButton, RedSection	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, GreenText.js, RedText.js, Text.js, Texts/index.js, numberFuntions.js	Button, GreenText, RedText, Text, getTenNumber, getThousandNumber	Text, Button

Explanation of JS bundle files

If we take a look at the file GreenSection.RedSection.js, we can see that commonly used modules of the GreenSection.js and RedSection.js modules are included, such as the Button.js and Text.js modules, as expected. So we have solved this issue. Note: The Button.js and Text.js modules are indirectly imported modules through RedText.js, GreenText.js, GreenButton.js and RedButton.js modules.
The bundle file GreenSection.RedSection.js also includes the GreenText, RedText, getTenNumber, and getThousandNumber functions. These functions should not be in this common bundle file and they are part of the common bundle file because Webpack splits bundle files according to their used common module and not used common function. According to our case, the GreenSection.js and RedSection.js modules import the same modules Texts/index.js and numberFunctions.js, so these modules and their dependencies are included in the common bundle module GreenSection.RedSection.js. The desired result we wantis that GreenText and getTenNumber should be in the GreenSection.js bundle file and RedText and getThousandNumber should be in the RedSection.js bundle file.

Let's analyze the CSS bundle files.

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenButton	GreenText, GreenButton
RedSection.css	RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, RedText, BlueText, GreenText, Button	Text, Button

Explanation of CSS bundle files:

.BlueText is included in GreenSection.RedSection.css even though it is unused. This happened because we import a barrel file of Texts/index.js that first loads the re-exported modules and while evaluating these modules it extracted CSS contents by the CSS loader and then eliminates unused code. It happened for the same reason as in the first example.
.RedText and .GreenText are included in GreenSection.RedSection.css, when they should included in RedSection.css and GreenSection.css, respectively. This happened for the same reason as we mentioned about their JS files, that they are indirectly imported through a barrel file. Webpack creates a common bundle file because the common module of Text/index.js is imported in both GreenSection.js and in RedSection.js.

Let's summarize the current opened issues:

Summary of Javascript issues:

GreenText and RedText modules are included in the common bundle file GreenSection.RedSection.js instead in their specific bundle files GreenSection.js and RedSection.js, respectively. Because they are imported indirectly through a barrel file Texts/index.js that it is the common module. If we will want to render one section file instead of the two sections, then we will download unused code. For example, if we load a page that renders only GreenSection component but conditionally renders RedSection component, then the downloaded bundle will include RedText.js even though we don't need it now.
GreenSection.RedSection.js bundle file include getTenNumber and getThousandNumber functions instead GreenSection.js bundle file include only getTenNumber and RedSection.js bundle file include only getThousandNumber.

Summary of CSS issues:

.BlueText exist in common bundle CSS GreenSection.RedSection.css even it is unused.
.RedText and .GreenText shouldn't be in GreenSection.RedSection.css bundle file. They should be in RedSection.css and GreenSection.css, respectively. The behavior of .RedText and .GreenText happened because the using of barrel file.

Our conclusions for now:

Using direct import instead of indirect import (barrel files) solves most of the issues.
Using one function per module instead of multiple functions per module solves the issues of the numberFunctions module.

Manual configuration of `sideEffects` solution

One of our conclusions in the previous example was that the use of barrel files can cause issues when dynamic import is used. It seems that usedExports marks unused exports for the whole code as a one bundle file only and not for each separate bundle file. When we made direct imports with the GreenButton and RedButton components, it worked properly.

In my Tree shaking in Webpack article, we learned that we can manually configure which modules in our project have side effects and which don't.

Also from that article, we know for sure that CSS files are considered to have side effects, so we need to flag them with side effects. Barrel files in our case only have re-exported functions, so we can say that we don't use direct imports from barrel files and they also don't have side effects, so we can flag barrel files without side effects.

Webpack's team talked about the purpose of the manual sideEffects property in their conference and explained that it comes to solve the issue of big bundle files when using of barrel files.

So let's try to solve our issues from the previous example with a manual configuration of sideEffects in package.json.

Let's clone the previous example 3-splitChunks to 4-package-sideEffects and change the package config file as follows:

package.json

{
  "name": "example-module",
+ "sideEffects": ["*.css"],
}

Now run npx webpack in the terminal window.

Let's take a look in the browser and check the rendered page:

We see that the Blue strong component (Direct Import) text is black when it should be blue. This is a visual issue. Why did this strange behavior occur?

First, let's look at the dev tools:

We can see that .Strong overrides .BlueStrong because .Strong is in a higher position. Why did this change? In the previous examples, .BlueStrong overrode .Strong. This happened because of the sideEffects property.

So I started to research this issue.

I found an issue where Hypnosphi complained that there were differences between development and production when he configured sideEffects: false, so he noticed that the order of CSS was not the order of the imports but the usage order. In another issue, there is an answer from sokra (a Webpack team member) who wrote:

Technically using sideEffects you say order doesn't matter

Another answer from sokra:

If the order of some modules matter they are not side-effect-free.

So let's go back to our case.

We evaluate the BlueStrong.js module that first imports the Strong component and then BlueStrong.css. But because we flagged modules with sideEffects manually, Webpack will first evaluate import module statements flagged with side effects and then evaluate used modules flagged without side effects in the order of their use. So the import of BlueStrong.css will be evaluated first and then we use the Strong.js that will be evaluated with Strong.css inside of it.

Let's analyze bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js, GreenText.js	GreenButton, GreenSection, GreenText	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js, RedText.js	RedButton, RedSection, RedText	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, Text.js, numberFunctions.js	Button, Text, getTenNumber, getThousandNumber	Text, Button

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenText, GreenButton	GreenText, GreenButton
RedSection.css	RedText, RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, Button	Text, Button

In the CSS table above, we can see for the first time that CSS files have the expected class selectors. So for now, we know for sure that the size of the CSS files is as small as possible.

Let's check if our previous example issues are solved:

GreenText and RedText are in their correct bundle files GreenSection.js and RedSection.js, respectively. sideEffects solved the issue of imported modules from barrel files.
.BlueText, which previously existed in the common bundle CSS file GreenSection.RedSection.css even though it was unused, is now eliminated. .RedText and .GreenText are in RedSection.css and GreenSection.css, respectively. sideEffects solved the issue caused by the barrel file.
getTenNumber and getThousandNumber still exist in the GreenSection.RedSection.js bundle file instead of getTenNumber being only inside GreenSection.js and getThousandNumber being only inside RedSection.js.

Let's summarize the current open issues:

getTenNumber and getThousandNumber still exist in the GreenSection.RedSection.js bundle file, instead of having only getTenNumber in GreenSection.js and only getThousandNumber in RedSection.js.
.Strong overrides .BlueStrong when it should be the opposite. This is a result of the sideEffects: ["*.css"] configuration that changing the order of imports based on usage of a module rather than by the order of import statements (except for CSS imports). This causes a visual issue.

I have considered several solutions for the second issue:

Convert CSS files to CSS Modules and change the sideEffects: ["*.css"] configuration to sideEffects: false.
Create a plugin that moves all CSS import statements to the end of the module if sideEffects: ["*.css"] is defined in package.json.
Change import statements from indirect imports through a barrel file to direct imports.

All of these solutions should work, but the first two solutions with configuration of sideEffects in package.json will change the import order to be determined by usage. The third solution, on the other hand, follows the order of import statements as ES Modules behavior. Since I want to follow my principle of having the bundle file resemble ES Modules behavior, the third solution is the better choice.

We still want to use barrel files because they make our code more readable and improve our developer experience. In the next chapter, we will try to develop an automatic transformation for our code that changes indirect imports through a barrel file to direct imports.

babel-plugin-transform-barrels

I know that Babel can transform code during the build process of Webpack. So I found some plugins (#1, #2, #3) that will transform the import statements from indirect import (through barrel file) to direct import, but all of them require specific configuration for each package. So I decided to develop a Babel plugin that will transform code with imports from barrel files into code with direct imports without needing configuration.

Kent C. Dodds talked about the problem of unnecessary CSS class selectors in this video and about his solution. It is based on a plugin that requires specific configuration, something that I don't want.

During the bundling process, my babel plugin transforms the line of code as follows:

From an indirect import (barrel file):

import { RedText } from "../../Texts";

To a direct import:

import { RedText } from '../../Texts/RedText/RedText';

My babel plugin prevents the inclusion of unused reexported modules from barrel files in the bundle file. This leads to a reduction in bundle size, thereby improving overall performance.

Now, let's install the plugin:

npm install --save-dev babel-plugin-transform-barrels

Now we need to add the plugin to the webpack config file which has a rule with a loader of babel-loader:

webpack.config.js

      {
        test: /\.(js|mjs|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        loader: require.resolve("babel-loader"),
        options: {
          presets: [["@babel/preset-react"]],
+         plugins: [["transform-barrels", { webpackConfigFilename: __filename, ...(typeof module.exports === "function" && { args: arguments })}]],
        },
      },

Now run npx webpack in the terminal window.

Let's take a look in the browser and check the rendered page:

We see that the "Blue strong component (Direct Import)" has the blue color as expected.

Let's look at the dev tools:

So even though the CSS table in this example is the same as in the previous example, the rendered page is different because now class selectors are loaded in the order of their import statements, as expected, rather than in the order of their usage.

We can see that .BlueStrong overrides .Strong, so this issue is solved.

Let's analyze bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js, GreenText.js	GreenButton, GreenSection, GreenText	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js, RedText.js	RedButton, RedSection, RedText	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, Text.js, numberFunctions.js	Button, Text, getTenNumber, getThousandNumber	Text, Button

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenText, GreenButton	GreenText, GreenButton
RedSection.css	RedText, RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, Button	Text, Button

As we can see in the Javascript and CSS tables above, there is no difference compared to the previous example 4-package-sideEffects.

Let's summarize the current open issues:

getTenNumber and getThousandNumber still exist in the GreenSection.RedSection.js bundle file instead of getTenNumber being only included in GreenSection.js and getThousandNumber being only included in RedSection.js.

The numberFunctions.js module has 3 function exports. If we split the module into 3 separate modules, each with one function export, it should resolve the issue.

Function per module

Before I try my optional solution, I searched for open issues on Webpack's Github repository and found the same issue we faced, but there is no solution provided by the Webpack team.

I checked a popular package with tree shaking support called Lodash. Lodash has a separate module per function. This allows the package to fully support tree shaking.

We will try this approach and see if it resolves our issue from the previous example.

Let's clone the previous example 5-babel-plugin to 6-function-per-module.

Now let's split the exports getTenNumber, getHundredNumber, and getThousandNumber from src\tools\numberFunctions\numberFunctions.js into 3 modules: getTenNumber.js, getHundredNumber.js, and getThousandNumber.js, respectively. And create a barrel file for the src\tools\numberFunctions directory. Now change the import statements of these functions in the GreenSection.js and RedSection.js modules.

Now run npx webpack in the terminal window.

Let's take a look in the browser and check the rendered page:

Everything looks great in our rendered page.

Let's analyze bundle files:

Javascript bundle files

Bundle file	Bundled modules	Actual functions	Expected functions
main.js	App.js, BlueStrong.js, Strong.js	BlueStrong, Strong	BlueStrong, Strong
GreenSection.js	GreenButton.js, GreenSection.js, GreenText.js, getTenNumber.js	GreenText, GreenButton, GreenSection, getTenNumber	GreenText, GreenButton, GreenSection, getTenNumber
RedSection.js	RedButton.js, RedSection.js, RedText.js, getThousandNumber.js	RedText, RedButton, RedSection, getThousandNumber	RedText, RedButton, RedSection, getThousandNumber
GreenSection.RedSection.js	Button.js, Text.js	Text, Button	Text, Button

CSS bundle files

Bundle file	Actual classes	Expected classes
main.css	BlueStrong, Strong	BlueStrong, Strong
GreenSection.css	GreenText, GreenButton	GreenText, GreenButton
RedSection.css	RedText, RedButton	RedText, RedButton
GreenSection.RedSection.css	Text, Button	Text, Button

Now getTenNumber and getThousandNumber no longer included in the GreenSection.RedSection.js bundle file. Instead, getTenNumber is included only in GreenSection.js and getThousandNumber is included only in RedSection.js.

We have successfully overcome all of our performance and visual issues. Now our project is optimized. We managed to minimize the size of the project by reducing the amount of CSS and Javascript code. The project only loads what it needs.

Summary

In this article, we encountered inefficient bundle files and visual issues in the browser when using barrel files with dynamic import that caused our bundle files to split into different chunks with unused Javascript code. We conducted a step-by-step examination to determine the best way to solve these issues.

We found 2 particular reasons for the issues:

Using barrel files in our code.
Using a module with more than one export.

The issues occurred because usedExports and sideEffects optimizations performed at the entirely code. So for example, in the numberFunctions.js module, usedExports first checks if its exports are used and sees that the getTenNumber function export is used by GreenSection and the getThousandNumber function export is used by RedSection and the getHundredNumber function is not used anywhere so it marks only getHundredNumber as an unused harmony export. Only after this evaluation of code, Webpack inject the code of numberFunctions.js module with the optimizations that were made into GreenSection.js and RedSection.js bundle files as we saw in the 2-lazy-loading example.

The way we solved each issue:

Using a Babel plugin babel-plugin-transform-barrels that transforms indirect imports (barrel files) into direct imports during the bundle process.
Splitting modules with more than one function into several modules with one function each.

I hope that in the future, the Webpack team will address and resolve the issues I have demonstrated in this article without any special plugin or configuration.

Additional Resources:

Your Next.js Bundle Will Thank You - It's about barrel files and sideEffects solution.
Do a barrel export - A brief overview of tools for barrel files.

Tree shaking in Webpack

Fogel — Mon, 17 Jul 2023 13:15:13 +0000

Introduction

Javascript file size can have a significant impact on browser performance. Unused code increases the size of our bundle file and as a result causes performance issues.

Delivering less JavaScript can mean less time in network transmission, less spent decompressing code and less time parsing and compiling this JavaScript - Addy Osmani

One effective way to reduce Javascript file size is through tree shaking.

Tree shaking is a term commonly used in the context of Javascript module bundlers. It refers to the process of removing unused code from the final bundle.

It is a powerful feature that can help you optimize the size of your Javascript bundle files. Despite its usefulness, many developers are still unfamiliar with how it works and how to use it effectively. After researching the topic and encountering some common issues, I decided to write a comprehensive guide to tree shaking in Webpack.

In this article, we'll explore how tree shaking works in Webpack and how you can use it to optimize your code. Through examples and visualizations, we'll explain the process of tree shaking step by step and help you optimize your code for better performance.

TL;DR

When building a production bundle in Webpack, the tree shaking process occurs automatically. The optimization properties of usedExports and sideEffects are enabled by default, leading to automatic optimization of the bundle files.

The main purpose of manually configuring sideEffects is to eliminate unused reexported modules within barrel files, resulting in a significant reduction in bundle size, improving performance and loading times.

Webpack

Webpack's main role is to bundle all module files into one or several files and minimize their size to save time and reduce server requests. Typically, we provide one entry point (the main Javascript file) to the Webpack config and then bundle files are created.

When executing regular Javascript (non-bundled), ES Modules evaluate every imported module file even if the imported specifier of the module is not used because the module can have side effects.

According to ECMA spec:

Do nothing if this module has already been evaluated. Otherwise, transitively evaluate all module dependences of this module and then evaluate this module

To resemble the behavior of ES Modules, Webpack includes every imported module's code (a dependency) in the bundle file without any elimination of code (except for optimization features).

Bundle Javascript project (development mode)

Let's create an example of regular Webpack bundle files without optimization.

In this example, we'll demonstrate how webpack bundles different files types (JS/CSS) into one file type main.js and main.css.

We'll use development mode because it does not have any optimizations configured by default.

To see the differences between different mode configurations (production/development/other) you can refer to the defaults.js file.

Let's take a look at the Webpack configuration:

webpack.config.js

//...
module.exports = {
  mode: "development",
//...

}

Before we run the webpack command, let's take a look at our code:

App.js

import { GreenText } from "./components/Texts/GreenText/GreenText";
import { RedText } from "./components/Texts/RedText/RedText";
import { getHundredNumber } from "./tools/numberFunctions/numberFunctions";
import { getUnusedModuleText } from "./tools/unusedModule/unusedModule";
import "./tools/sideEffectsModule/sideEffectsModule";

function App() {
  const hundredNumber = getHundredNumber();
  return (
    <>
      <GreenText>Number in green: {hundredNumber}</GreenText>
      <RedText>Text in red</RedText>
    </>
  );
}

export default App;

From the code above, we can see that we have GreenText and RedText components, the getHundredNumber function and the sideEffectsModule module in App.js. We also import an unused function getUnusedModuleText. These components, functions and module use different modules through direct import:

The component GreenText is from the module "./components/Texts/GreenText/GreenText.
The component RedText is from the module "./components/Texts/RedText/RedText".
The function getHundredNumber is from the module "./tools/numberFunctions/numberFunctions", which contains another two functions (getTenNumber, getThousandNumber).
the unused function getUnusedModuleText is from the module "./tools/unusedModule/unusedModule", which contains another function (getUnusedModuleButton).
A side effect import module that is imported from "./tools/sideEffectsModule/sideEffectsModule", which contains global code with side effects.

In the bundle process we expect that it will produce two files (JS and CSS files).

Let's run npx webpack in the terminal window.

The build process created two files as expected: main.js and main.css.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that all functions and global code from all imported modules are included in the file. Even functions that weren't imported as a specifier in the import statement are included in the bundle file. As we mentioned earlier, Webpack resembles the behavior of ES Modules by importing the entire code of modules including unused code (dead code).

Even the following unused functions are included:

The unused function getUnusedModuleButton from the unused module ./tools/unusedModule/unusedModule.
The unused functions getTenNumber and getThousandNumber from the used module ./tools/numberFunctions/numberFunctions.

Note: The BlueText and BlackText are not included because they haven't been imported anywhere.

When importing from a re-exported module, for example, a barrel file, Webpack will evaluate all re-exported modules as having side effects even if some of the re-exported modules aren't imported or used. The reason for this is written in the official Webpack example of side effects:

According to the EcmaScript spec, all child modules must be evaluated because they could contain side effects.

Sean from the Webpack team also explained this on Stack Overflow:

According to the ECMA Module Spec, whenever a module re-exports all exports, (regardless if used or unused) they need to be evaluated and executed in case one of those exports created a side-effect with another.

The used and unused functions are marked in the main.js bundle file by the comment "harmony export".

These unused functions (also known as dead code) increase the size of our bundle file and cause performance issues.

To improve performance, we prefer to carefully delete unused code and make our bundle file as small as possible.

In the main.css file, we can see both class selectors of .GreenText and .RedText.

The term for dead code elimination is called Tree shaking and we will discuss it in the next chapter.

Tree Shaking

During the build process, Webpack creates a dependency tree structure. In the tree, each dependency (module) is represented by a branch and each function is represented by a leaf. There are green branches (which represent modules with used functions or with side effects), light green leaves (which represent imported used functions), brown leaves (which represent unused functions from imported module, also known as "dead code") and dark brown branches (which represent imported unused modules with no side effects). When we shake the tree, the brown leaves should fall off while the green leaves remain. In our case, this means that after tree shaking only imported used functions or modules with used functions or side effects should remain.

As we saw in the last example, used and unused functions were marked the same with the comment "harmony export" that specifies the green leaves.

How can it be that unused functions were marked as green leaves? Because we were in development mode, which has no optimization enabled.

So how can we mark the unused functions as brown leaves and unused modules without side effects as dark brown branches? For this, we should use the optimization configuration.

Optimization

usedExports

The usedExports property is responsible for marking the unused functions with brown leaves.

Let's clone the previous example 1-without-optimization to 2-optimization-usedExports and change the Webpack config file as follows:

webpack.config.js

//...
module.exports = {
  mode: "development",
+ optimization: {
+   usedExports: true,
+ },
//...
}

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

Take a look at the bundle file:

main.js

//...
/* unused harmony exports getTenNumber, getThousandNumber */
function getTenNumber() {
  return 10;
}
function getHundredNumber() {
  return 100;
}
function getThousandNumber() {
  return 1000;
}
//...
/* unused harmony exports getUnusedModuleText, getUnusedModuleButton */
function getUnusedModuleText() {
  return "imported but unused module";
}
function getUnusedModuleButton() {
  return "imported but unused module";
}

In the main.js file we can see that Webpack with the usedExports: true property marked the unused functions (dead code) with the comment /* unused harmony export functionName */. This comment points to the unused function as a brown leaf in the tree.

But the entire unused function declarations are still in the file. How can we get rid of it? How can we shake the tree and cause brown leaves to fall down (eliminate dead code) to the ground? We will shake the tree later using either the configuration of minimize: true or mode: production .

In the main.css file, we can see that it's the same as in the first example 1-without-optimization.

sideEffects

First, let's explain what side effects are.

There are two types of code: pure code and code with side effects:

Pure code: It uses only variables from its scope and doesn't use global variables like the window object or data that comes from the outside sources such as HTTP requests, file system, DOM, etc. For example, a pure function always returns the same output for the same input and doesn't use global variables. In short, pure code is a code without side effects.
Code with side effects: It uses global variables or data from outside its scope. For example, a function that can return different output for the same input or a function that changes global variables like the window object or uses data from HTTP calls, file system, DOM, etc. In short, It is the opposite of pure code.

In Webpack, sideEffects configuration enables us to exclude entire module (and his dependencies) whose direct exports are not used and doesn't have side effects from the bundle file.

Point to remember to this section: In Webpack, the sideEffects configuration only affects imported modules whose direct exports are not used. Modules with used exports will always be included. An example of imported modules whose direct exports are not used are barrel files that re-export functions.

There are two configurations for sideEffects that are designed to work together if they configured:

The sideEffects property in the optimization object in webpack.config.js - Enable the use for manual configuration of modules with or without side effects and/or automatic analysis of modules for side effects.
The manual sideEffects property inside either package.json file or the module.rules array in the webpack.config.js file - Manually configure the list of modules that have or don't have side effects. In this case modules whose direct exports are not used flagged manually as having no side effects, then these modules and their dependencies will be safely excluded from the bundle file without even being evaluated.

sideEffects optimization

According to WebpackOptions.json, the optimization sideEffects property can have the following values:

true - Include or exclude modules depending on their manual configuration in the package.json or webpack.config.js file. Modules that haven't been flagged with or without side effects in the webpack.config.js file and whose exports are not used will be analyzed, if there are no side effects, they will be excluded.
"flag" - Only include or exclude modules depending on their manual configuration in the package.json or webpack.config.js file. Modules that haven't been flagged with or without side effects in the webpack.config.js file will be included as usual, just like we learned about ES modules.
false - It will not evaluate modules for side effects even if set in the package.json or webpack.config.js file. All imported modules will be included as we learned about ES modules.

Note

If the modules with side effects are flagged in the package.json file, the remaining files will be flagged as having no side effects. So if modules are configured through the package.json file, there will be no difference between the values true and "flag". The result of them will be the same because all modules are flagged with or without side effects and there is no module that isn't flagged. Then the true value will not have modules to analyze because all modules have been flagged with or without side effects, so true and "flag" will have the same behavior.
Production mode uses the optimization sideEffects value of true.

Before we dive into the manual way of configuring sideEffects, let's make an example about the optimization sideEffects property without manually defining which modules have or don't have side effects:

Clone the previous example 2-optimization-usedExports to 3-optimization-sideEffects and change the webpack config file as follows:

webpack.config.js

//...
module.exports = {
  mode: "development",
 optimization: {
   usedExports: true,
+  sideEffects: true,
 },
//...
}

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

Take a look at the bundle file:

main.js

//...
/* unused harmony exports getTenNumber, getThousandNumber */
function getTenNumber() {
  return 10;
}
function getHundredNumber() {
  return 100;
}
function getThousandNumber() {
  return 1000;
}
//...

In the main.js file, we can see that Webpack with the sideEffects: true property eliminates the unused module of unusedModule (dead code) compared to the previous example 2-optimization-usedExports which just marked unusedModule with /* unused harmony export getUnusedModuleText, getUnusedModuleButton */. When we use in mode: production, which under the hood uses minimize: true, for both the second and third examples, both bundle files will be the same because the unused unusedModule will be eliminated during the minimizing process.

In the main.css file, we can see that it's the same as in the first example 1-without-optimization.

sideEffects - Manually define

Now, if we set the optimization sideEffects property to true or "flag", we can help Webpack manually define which modules have side effects and which don't.

Sean from the Webpack team explains on Stack Overflow that we use the sideEffects configuration as a way to save on both compile time and build size because it excludes modules in advance that are flagged as having no side effects and whose direct exports are not used.

According to Webpack documentation:

sideEffects is much more effective since it allows to skip whole modules/files and the complete subtree.

usedExports relies on Terser to detect side effects in statements. It is a difficult task in JavaScript and not as effective as straightforward sideEffects flag.

Webpack's team talked about another purpose of the manual sideEffects property in their conference and explained that it comes to solve the issue of big bundle files when using of barrel files.

There are 2 ways to manually define which modules have side effects and which don't:

Package config file (package.json):

All package modules have no side effects:
```
{
  "name": "example-module",
  "sideEffects": false
}
```
Alternatively, an array of modules that have side effects (the remaining modules will be considered and flagged as having no side effects if they don't have used direct exports):
```
{
  "name": "example-module",
  "sideEffects": ["*.css", "*.scss"]
}
```

Webpack config file (webpack.config.js):

Use regular expressions to define all Javascript and Typescript files in the project as having no side effects and CSS files as having side effects:

module: {
  rules: [
    {
      test: /\.(js|mjs|jsx|ts|tsx)$/,
      sideEffects: false
    },
    {
      test: /\.s?css$/,
      sideEffects: true
    }
  ]
}

We know that CSS files are considered to have side effects, so we flag them as such. However, this is not mandatory and we can remove the rule for CSS files above. The result will be the same, it's just for protection. if someone later configures the package.json file with sideEffects: false, the rule in webpack.config.js for CSS will override the configuration in package.json

Webpack wrote a "Tip" about CSS files as described on Webpack website:

> Note that any imported file is subject to tree shaking. This means if you use something like css-loader in your project and import a CSS file, it needs to be added to the side effect list so it will not be unintentionally dropped in production mode.

Side effect import - import "filename.js"

In Side effect import also called "Empty import", It will need to be included if there are side effects inside it. This can include, for example, global code and CSS files.

import "filename.js";
import "filename.css";

In our examples, we use a module with side effects called sideEffectsModule. Note that this module has no exports but have side effects cause it affects window object. So this kind of module can easily be excluded from the bundle file if it is configured incorrectly and not included in the array of the sideEffects property in the package.json file.

So let's make a manual configuration of sideEffects in the package.json file.

Let's clone the previous example 3-optimization-sideEffects to 4-package-sideEffects and change the package config file as follows:

package.json

{
  "name": "example-module",
+ "sideEffects": ["*.css"],
}

Alternatively:

webpack.config.js

module: {
  rules: [
    {
      test: /\.(js|mjs|jsx|ts|tsx)$/,
+     sideEffects: false
    }
  ]
}

In our example we use only the package.json option, but both options have the same result.

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that it is similar to the previous example (3-optimization-sideEffects) except that the content of sideEffectsModule is not included. This occurred because sideEffectsModule doesn't have any exports and was flagged as having no side effects. As a result, Webpack doesn't evaluate it for side effects and simply skips over the sideEffectsModule module.

In the main.css file, we can see that it's the same as in the first example (1-without-optimization).

So what are the differences between the third and fourth examples except the missing global code of sideEffectsModule module? It's about compile time, as we talked earlier about Sean from the Webpack team. In the fourth example, Webpack skips over modules with unused exports that have been flagged as having no side effects without attempting to evalute them for side effects.

sideEffects - Manually define fixed

Let's make the same example but this time we will correctly configure the package.json file.

package.json

{
  "name": "example-module",
- "sideEffects": ["*.css"],
+ "sideEffects": ["*.css", "sideEffectsModule.js"],
}

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that now it fixed and sideEffectsModule module content is included in the bundle file.

Note - Manually configuring sideEffects issue

I found an issue where Hypnosphi complained that there were differences between development and production when he configured sideEffects: false. He noticed that the order of CSS was not the order of the imports but the usage order. In another issue there is an answer from sokra (a Webpack team member) who wrote:

Technically using sideEffects you say order doesn't matter

Another answer of sokra:

If the order of some modules matter they are not side-effect-free.

I will expand on this in the article Potential issues with barrel files in Webpack talking about issues with optimization configuration and how to solve them.

If I only import the modules that I use, why should I use the sideEffects property? It's useful for modules that only re-exports functions from other modules. For example, barrel files that are used inside modules that are dynamically imported. I will expand on this in my next article.

Summarize the sideEffects configuration in a diagram:

Production mode

The last thing that remains to check is the production bundle.

Production mode has different optimization values compared to development mode. We can see in the default.js file that minimize is set to true.

The minimize property is used as the final tree shaking step. It eliminates unused exports (brown leaves) that were marked by usedExports.

Let's clone the third example 3-optimization-sideEffects to 6 - production and change the webpack config file as follows:

webpack.config.js

  //...
  module.exports = {
+   mode: "production",
-   mode: "development",
-   optimization: {
-     usedExports: true,
-     sideEffects: true,
-   },
//...
  }

Now run npx webpack in the terminal window.

Let's demonstrate it in a dependency tree:

In the main.js file, we can see that it's significantly smaller file. It only includes what's needed and mangles the variable and function names.

In the main.css file, we can see that it has changed here because it eliminated comments in the file compared to previous examples.

After optimizing and minifying our bundle file, let's take a look at the results.

As shown in the screenshot, the size of the JS files has decreased significantly - from 1.36kb to 626 bytes, a reduction of 54%. This is a substantial decrease in size.

Tree shaking summary steps

Eliminating imported modules whose direct exports are not used and don't have side effects with sideEffects configuration.
Mark the brown leaves (comment: /* unused harmony export functionName */) with the usedExports: true property.
Shake the tree (eliminate dead code) with the minimize: true or mode: production property.

Dynamic imports

This article will not cover the topic of tree shaking dynamic imports. For an in-depth explanation of this subject, please refer to the awesome article Dynamically Import ESModules and Tree Shake them too!.

Summary

In this article, we explored the concept of tree shaking in Webpack to optimize your bundle file. We explained how tree shaking can be used to remove unused functions and modules (dead code) from the final bundle and which optimization properties involved in that through examples and visualizations. The main purpose of this article was to ease the tree shaking subject and I hope that I succeeded in that.

I recommend reading my next article on Potential issues with barrel files in Webpack.

Additional Resources:

Reduce JavaScript payloads with tree shaking

Tree Shaking in official Webpack website

Deep Dive Into Tree-Shaking

How to build tree-shakeable JavaScript libraries

JavaScript Start-up Optimization

DEV Community: Fogel

How Default Settings and Bad Habits Are Draining Your Claude Code Budget

Introduction

Baseline Assumptions

Features that consume tokens

Session recap

Is it added to the context?

Does this action consume tokens?

My recommendation

How to disable

Prompt suggestions

Is it added to the context?

Does this action consume tokens?

My recommendation

How to disable

opusplan model setting

Auto memory

Is it added to the context?

Does this action consume tokens?

My recommendation

How to disable

Auto mode

Does this action consume tokens?

My recommendation

How to disable

Disable Auto Mode entirely

Prevent Auto Mode during Plan Mode

Shell mode with ! prefix

Is it added to the context?

Does this action consume tokens?

My recommendation

How to disable

Language Server Protocol (LSP) plugins

Is it added to the context?

Does this action consume tokens?

My recommendation

Installing the plugin

Context command (/context)

Is it added to the context?

Does this action consume tokens?

My recommendation

Workflow Best Practices (Beyond Settings)

Delegate verbose operations to subagents

Side questions with /btw command

Rewinding the conversation

Course-correct early (The ESC Key)

Is it added to the context?

Does this action consume tokens?

Beware of Cache Misses on Idle Sessions

My recommendation

Resetting to a Clean Session

Is it added to the context?

Does this action consume tokens?

Workaround

Conclusion

How to Reduce Claude Code's Initial Context and Avoid Prompt Cache Breaks

Introduction

What is Initial Context?

How does Prompt Caching work?

TL;DR

Results by Component

How were the tests performed?

How did I measure the number of tokens?

Test Environment

Deep Dive by Component

1. Artifact

What does it add to the context?

Impact on Prompt Caching

Summary of disabling Artifact:

How to disable:

2. Git Instructions

What does it add to the context?

Impact on Prompt Caching

Trade-offs

My Recommendation

How to disable:

3. Auto Memory

What does it add to the context?

Impact on Prompt Caching

Ongoing Token Consumption During the Conversation

`opusplan` model setting

Shell mode with `!` prefix

Context command (`/context`)

Side questions with `/btw` command

Manual configuration of `sideEffects` solution