Introduce overlayStyleMode option to manage overlay styling behavior

[ertgl]

Summary

• Add overlayStyleMode option with two possible values: inline (default) and headless.
• Add client-overlay.css file containing the default styles.
• Fix CSP violation #457.
• Update README.md, describe overlayStyleMode.
• Add examples for csp and headless-styling scenarios.

What kind of change does this PR introduce?

• feat
• fix

Did you add tests for your changes?

CSP scenario:

# Reproduction for the CSP violation:
# Open /csp path, trigger an error, see the console logs.
# CSP must be violated. Styles must be blocked.
npm run start:csp::violate

# Open /csp path, trigger an error, see the console logs.
# No violation must be observed. Default styles must be applied without any issues.
npm run start:csp

Headless-styling scenario:

# Open /headless-styling path, trigger an error.
# `ERROR` label must be white on black, only.
npm run start:headless-styling

Does this PR introduce a breaking change?

No.

If relevant, what needs to be documented once your changes are merged or what have you already documented?

Documented in the README.md:

• Description of the overlayStyleMode option.
  • Default is inline.
  • Headless mode is for custom or CSP-compatible styling.
    • webpack-hot-middleware/client-overlay.css can be imported to enable the default styles.
    • Requires a loader to be configured for CSS files.
• overlayStyles option requires overlayStyleMode to be inline.

Not documented:

• CHANGELOG.md

[alexander-akait]

Sorry, we can't use it here, because it will be this module for many people, we need to search another solution for this problem

[ertgl]

Thanks for the review. I implemented the current solution by considering all possible scenarios. By default, I intentionally did not auto-import the CSS file so that no loader is required out of the box. When CSP-compatible styling is needed, the CSS file must be imported by user manually, which naturally requires a CSS loader to be configured.

The style-loader and file-loader here are used only for the csp example (not the package itself):
https://github.com/ertgl/webpack-hot-middleware/blob/fee93b3c934579dde5b54d49770dd8598870c965/example/webpack.config.csp.js#L34

With this approach, users can integrate the package into their own setups using their preferred loaders, or without any loaders at all. If I misunderstood your point, I'm happy to revisit it.

[alexander-akait]

To be honest, I'm more interested in why inline styles aren't allowed in development mode... but I am open to any solution, I just want to understand that this problem is really worth these workarounds instead of allowing inline styles in development mode

[ertgl]

Some projects, especially security-sensitive ones (e.g. legal-related), enforce CSP consistently across all environments to prevent issues early. Some developers also aim to keep their development environment as close to production as possible, while some teams work directly on staging servers over SSH to share results with other departments. So the CSP aspect is just one part of that consistency; the broader goal is maintaining full control over quality and velocity, regardless of the environment. As a small benefit, by disabling inline styles in development, it becomes a written rule for the project, and the browser acts like a nice real-time linter, helping catch issues before tests even run.

Currently, the package interrupts such disciplines. Allowing inline styles for a single development package can also open the door for other third-party packages to accidentally inline styles, giving developer the impression that "it worked, so it's finished." I see this as an opt-in feature containing the fix, instead of a workaround.

[ertgl]

I've added a description of why we install file-loader and style-loader in the example package.