My Journey with Astro

[vralle]

Hi folks!
I’ve been working with Astro over the past few months on several production projects, and I wanted to share my experience - not just highlighting the fantastic developer experience it offers but also discussing some limitations and how I’ve worked around them. I’m opening this thread to hear how others in the community are approaching similar challenges, and to thank the author of html-bundler-webpack-plugin for a truly excellent tool.

---

What Makes Astro a Joy to Work With

• TypeScript support out of the box - Enjoy strict typing without extra config hassle.
• JSX/TSX within HTML - Full component logic and type checking directly inside your templates.
• Frontmatter brilliance - Define dynamic props, scripts, styles, and component logic seamlessly in a single place.
• Content collections with types - Clean templating and strong typing across multiple content entries.
• VS Code integration - Autocompletion, validation, and template hints work flawlessly thanks to the official plugin.

Together, these features make for a fantastic DX. The framework feels natural, intuitive, and pleasant to work with - whether you're prototyping or building a full-scale product.

---

Where Things Get Tricky: Asset Handling & Output Control

Astro provides some support for output file renaming (via Rollup settings), but it's limited. In particular:

• You don’t have access to the original file path, which makes this system impractical for batch renaming or mapping assets predictably.
• This is critical when working with user-generated content, image pipelines, or maintaining clean filename conventions.

Additionally:

• Using globs or importing images through variables always causes the source files to be included in the final build, regardless of whether they are truly needed or sensitive.
• There’s no built-in way to exclude unused image references or enforce sanitized asset outputs.

---

Solution: Webpack + html-bundler-webpack-plugin for Deep Optimization

To regain full control over the final production output, I’ve adopted a hybrid approach: exporting the Astro build and feeding it into Webpack with html-bundler-webpack-plugin.

This enables deep, layered optimization across the entire project, including:

• Precise control over file naming and paths - HTML, CSS, JS, image assets
• Dead code and asset removal - unused fragments never make it into production
• Injection and consolidation of inline assets - custom strategies for script/style loading
• Custom pipelines - apply your own plugins and transforms at every stage

This approach bridges the gap between Astro’s excellent DX and real-world production needs-giving me the confidence that the final bundle is clean, consistent, and secure.

@webdiscus, huge thanks for creating such a powerful tool - it has become essential in my build workflow 🙏

[webdiscus]

Hello @vralle,

Thanks for your feedback and for sharing your complex usage example.
Unfortunately, there aren't many people active here.
For broader reach and more diverse developer input, you might want to try posting on dev.to or Reddit.

[vralle]

Hello @webdiscus

Unfortunately, there aren't many people active here.

There are a few broader questions that I believe are deeply connected to the adoption of tools like html-bundler-webpack-plugin.

1. I have yet to encounter a developer experience (DX) as smooth and enjoyable as what Astro provides.
2. Setting up a full-featured Webpack pipeline is rarely as straightforward as it is in Astro or even 11ty.

These two points are closely related. In fact, I believe Webpack itself has faced some community friction due to the sheer diversity and complexity of its ecosystem. While it's incredibly powerful, that power often comes at the cost of accessibility.

One potential way to attract more users could be to position this plugin explicitly as a tool for deep optimization. That’s exactly what it already excels at. And in an era where even Google and modern AI-driven platforms struggle with bloated or poorly structured websites, this kind of control is more relevant than ever-though I suspect the results may not always be immediately impressive to the average developer.

That said, I personally consider this plugin irreplaceable when a project demands full control and deep optimization of HTML, CSS, JS, and assets. It fills a critical gap that most modern frameworks simply don’t address.

Thanks again for your work on this - it's a rare and valuable piece of tooling.

[vralle]

I’ve been thinking a lot about template engines lately, especially after working with Astro. It gave me some fresh ideas about how this plugin might be improved.

Even though the plugin is a powerful tool, the template engines are definitely the weakest link in the pipeline. For example, Eta has a few limitations:

• No type support in IDEs
• If you’re using a layout for multiple pages, it’s not easy to add page-specific styles to the <head>. You’re pretty much stuck with (both approaches feel messy):
  • injecting styles via JavaScript, or
  • passing individual page data with styles and rendering manually
• When it comes to using Markdown/MDX/whatever in templates, the engines compile code in isolation. They don’t understand Webpack or its loaders.

Astro solves many of these problems out of the box, but right now I’d love to focus on one thing: importing inside templates.

The plugin does support Markdown imports although that part isn’t documented. I’ve made my own Eta fork to add Markdown support.

Working with different content file formats made me think:

Wouldn’t it be amazing if Eta loader passed file handling to Webpack directly?

This way, we could use Webpack loaders for Markdown, MDX, Front Matter, or anything else. and benefit from full compatibility and flexibility.

@webdiscus, I’d love to hear your thoughts on this idea and any insights into how tricky it might be to implement.

Let me know if you want help sketching it out or experimenting with a proof of concept!

[webdiscus]

I like your idea to improve Eta. All this should be implemented in the template engine, not in the plugin.

using a layout for multiple pages, it’s not easy to add page-specific styles to the <head>

Many others template engines support layouts or helpers that allow you to add page-specific styles and scripts:

• Pug resolve-js-css-multipage
• Handlebars handlebars-page-specific-js-css
• Nunjucks nunjucks-options
• Twig twig-options

Since this is a templating engine feature, the plugin shouldn't use any "black magic" to implement it. The solution is to simply use the right templating engine.

The plugin does support Markdown imports although that part isn’t documented.

This feature is experimental therefore is not documented. I need more tests, more different complex use cases to cover all possible usage scenarios.

we could use Webpack loaders for Markdown, MDX, Front Matter, or anything else. and benefit from full compatibility and flexibility.

Everything is required, will be passed to Webpack directly. But to use it in any template engine, we need own specific syntax to load external resources via Webpack loader, e.g.: require(file.mdx) (this approach is already used in Pug) or __load(file.mdx), etc. This placeholder can be parsed by plugin and inner generate correct require code, e.g.:
... MDX partial:' + require('./path/to/file.mdx') + '....
The result of this require is the string content generated by Webpack specific loader.

Can you provide your vision, code examples for "Should be", then we can discuss about.

[vralle]

@webdiscus, just to be objective - I don’t have much experience with different template engines. Right now, Eta is my main templating tool, and it’s the only one I can confidently speak about based on actual usage.

Currently, the most obvious way to handle different file formats in Eta is by extending its class. Eta uses include() for importing templates and calls readFile() internally. There are two main approaches I’m considering:

1. Add specialized template functions for importing specific file types, like includeMd(path), includeMdx(path), etc. These could route the content through the appropriate transformer.

2. Add a file format analyzer inside readFile() itself, which would manage content transformation based on file type.

I’ve also been thinking about the simplest path: creating custom content integration mechanisms that can be injected into Eta through the data object, like:

data: {
  mdLoader,
  mdxLoader
}

This wouldn’t integrate with Webpack, the transformations would remain isolated.
Either way, the discussion here has given me valuable insight into other template engines, and I’d really like to try them out in practice. Maybe my opinion will evolve after that.

[vralle]

Everything is required, will be passed to Webpack directly.

I've was trying with Eta. required not works for package type module.
ReferenceError: required is not defined
ReferenceError: __load is not defined

And import doesn't woks either.
template:

{{ const content = import("../content/privacy-policy.md") }}
{{~ content.default }}

Result:

node:internal/modules/esm/resolve:275
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/workspaces/node_modules/eta/content/privacy-policy.md' imported from /workspaces/node_modules/eta/dist/eta.module.mjs

import() runs from Eta location (workspace), and knows nothing about package with site

[webdiscus]

import != require

[vralle]

package type module :(

ReferenceError: required is not defined
ReferenceError: __load is not defined

[webdiscus]

How works Webpack Loader

A loader for a template engine transforms a source template into JS module:

module.export = 'Hello World! <img src="' + require('/abs/path/to/image.png') + '">'; // injected require() is result of a loader

This JS code will processed via Webpack. The required file will be processed via module.rules (e.g., via asset/resource, svg-loader, etc). Then the plugin capture required resources and replaces resolved source paths to output filename generated by Webpack.

How works the plugin

[webdiscus]

package type module :(

ReferenceError: required is not defined
ReferenceError: __load is not defined

That was a suggestion. It must be implemented in the loader.

Look how works include in built-in eta loader

[vralle]

@webdiscus, I'm confusing.

Webpack Loaders:

    {
        test: /\.md$/,
        use: [
          {
            loader: "remark-loader",
            options: {
              remarkOptions: {
                plugins: [RemarkHTML],
              },
            },
          },
        ],
    },

The plugin:

      preprocessor: "eta",
      preprocessorOptions: {
        cache: false,
        cacheFilepaths: false,
        defaultExtension: ".html",
        rmWhitespace: true,
        tags: ["{{", "}}"],
        useWith: true,
        views: join(projectPaths.src, "views"),
      },

In template:
{{~ include("@src/content/privacy-policy.md") }}: EtaNameResolution Error: Failed to get template '@src/content/privacy-policy.md'
{{= require("@src/content/privacy-policy.md") }}: ReferenceError: require is not defined

Now I'm confusing (

[vralle]

It seems strange, but the loader only processes the first file, then the compilation of the second one fails.

[webdiscus]

I try to write a test case to include many MD files...
It's experimental feature, but I will improve it ;-)

[webdiscus]

Here is the test case where are included many *.md files in the Eta tempate eta-include-md-many-files

<%~ include('/src/markdown/code.md'); %>
<%~ include('/src/markdown/demo.md'); %>

Note: it will be processed via plugin loader, no Webpack loader for md is required.

P.S. to include a file and handle it via a Webpack loader - it's not implemented yet.

[webdiscus]

const includeRegexp = /=include\((.+?)(?:\)|,\s*{(.+?)}\))/g;

Fix: https://regex101.com/r/LRKCKU/1

what fix it?
Can you provide a Eta template example which fails with current plugin version?

[vralle]

thoughts

Locations Where new Eta() Is Created in html-bundler-webpack-plugin

File	Approx. Line	Context	Link
Preprocessors/Eta/index.js	~22	Creates const eta = new Eta() and overrides readFile	View file
Template.js	~40	Inside Template constructor: this.eta = new Eta(...)	View file
PreprocessorModeAbstract.js	~60	In compileTemplate: creates local const eta = new Eta(...)	View file

These are the locations where new Eta instances are created and the custom readFile method may be discarded.

---

Refactoring Plan: Centralizing the Eta Instance

Objective

Ensure a single shared Eta instance — with overridden readFile — is used throughout the plugin, including:

• Template.js
• PreprocessorModeAbstract.js
• Preprocessors/Eta/index.js

---

Step-by-Step Strategy

1. Export a Central Eta Instance with a Custom readFile

// src/Loader/Preprocessors/Eta/index.js
import { Eta } from 'eta';

const eta = new Eta();
eta.readFile = myCustomReadFile; // Custom logic here

export default eta;

---

2. Modify Template.js to Accept External Eta

// src/Loader/Template.js
constructor(options = {}, etaInstance) {
  this.options = options;
  this.eta = etaInstance || new Eta(); // fallback if none provided
}

And update wherever Template is instantiated (e.g. in Loader/index.js):

import eta from '../Preprocessors/Eta';

const template = new Template(options, eta);

---

3. Apply the Same in PreprocessorModeAbstract.js

Replace internal creation with external injection:

import eta from '../../Preprocessors/Eta';

compileTemplate(content) {
  const template = new Template(content, eta);
}

---

This way, the custom readFile logic will consistently be applied regardless of where the template is compiled or how includes are resolved.

[vralle]

what fix it? Can you provide a Eta template example which fails with current plugin version?

Here it is with original regexp: https://regex101.com/r/LRKCKU/3

[webdiscus]

what fix it? Can you provide a Eta template example which fails with current plugin version?

Here it is with original regexp: https://regex101.com/r/LRKCKU/3

It's just online-simulator, in real use case it's work fine. Do you have the concrete use case that doesn't work?

[vralle]

I’ve added some more logging. At the moment, all I know is that include("file.md) for some reason doesn’t hit either the loadFile() method overridden by the plugin, or preprocessor.compile()

It’s possible I’m making a mistake in the regular expression.

[webdiscus]

ah, the includeRegexp used in compilation mode when a template is imported in JS file.
For render mode it doesn't work since eta.readFile is called.

[vralle]

@webdiscus, I'm going to take a break and investigate why compilation fails in my current setup. So far, the only possible cause I'm considering is that multiple Eta instances are being used during compilation, or that caching is involved since not all files show up in the logging output.

[vralle]

First +:
I remove all preprocessor options from the plugin's config and use default syntax: <%~ include("./src/content/privacy-policy.md") %>
I'd got a message: Error: Cannot find module 'prismjs'. Please install the missing module: npm i -D prismjs.
I did it and a compilation finished Ok.

[vralle]

Step 2: I've added preprocessor: "eta" into the plugin's config and have got error Error: ENOENT: no such file or directory, open '/workspaces/projects/site/src/views/src/content/privacy-policy.md' with the same setup)

[webdiscus]

can you provide a small repo with reproducible issue?

[vralle]

@webdiscus,
Sorry for dropping out of the conversation for a bit. I’ve been exploring the idea of adding an abstraction layer to Eta for content transformation.
Here’s my experimental implementation: vralle/eta-hooked

In my view, these changes offer a more systematic approach to versioning and content transformation, all without touching the core templating logic.

This version of Eta makes it possible to externalize the transformation hook into config, or even wire it into a Webpack pipeline. Total freedom for handling transformations: developers can define exactly which processors they want to use.

Would love to hear your thoughts!

[webdiscus]

Good idea. I prefer the name transform instead of transformer, like in rollup-plugin-copy.
We can add new hook in plugin for include to customize handling of includable files: *.md (built-in defaults), *.mdx, etc. - can be processed on user side.

[webdiscus]

P.S. the idea with require(file.any) -> Webpack processing for Eta - does not work, I experimented, without result.

[vralle]

I’m currently integrating the package into real production projects and will apply any required fixes or adjustments as they come up.

[vralle]

import EtaHooked from "@vralle/eta-hooked";
import MarkdownIt from "markdown-it";

const eta = new EtaHooked({
  cache: false,
  cacheFilepaths: false,
  defaultExtension: ".html",
  rmWhitespace: true,
  tags: ["{{", "}}"],
  useWith: true,
  views: join(projectPaths.src, "views"),

  /**
   * Transform template parts to html
   * @param {string} content
   * @param {string} filename
   * @returns
   */
  transformer: function(content, filename) {
    if (filename.toLocaleLowerCase().endsWith(".md")) {
      console.log(filename);
      return markdownIt.render(content);
    }

    return content;
  },
});

const webpackConfig = {
  ...
  plugins: [
    new HtmlBundlerPlugin({
       ...
       preprocessor: (content, { data }) => eta.renderString(content, data),
    }),
  ],
}

@webdiscus, I fixed typo in package name, republished it and tested in real project. Works well

[vralle]

v0.1.1: rename transformer->transform hook and update references

[vralle]

P.S. the idea with require(file.any) -> Webpack processing for Eta - does not work, I experimented, without result.

Hmm. Image links and more in templates are handled very efficiently by the plugin.

template-part.html:

<meta name="twitter:image" content="{{= meta.twitterCard.image }}" />
<meta property="og:image" content="{{= meta.openGraph.image }}">
<link href="@src/img/branding/safari-pinned-tab.svg" color="#0f3341" rel="mask-icon">
<link href="@src/site.webmanifest" rel="manifest">

All file types is configured in Webpack loaders and the plugin's sources option

[webdiscus]

The option sources allows to resolve an asset file via HTML parsing, but capture "included" file in a template must supported in self templating engine.
It's much much complex:

1. A template engine must provide an access to parsed AST (precompilation).
2. The plugin must analyse the AST, capture included file.
3. Captured file must be added to Webpack compilation as additional assets.
4. The plugin must detect processed captured file and replace it with a content generated by a loader.

This feature requires too much time to develop, and I'm not sure that the time spent will pay off if this feature is needed at all.

The easiest way is to write your own Eta preprocessor with processing of the necessary files (*.md, *.mdx, etc.).

P.S.

It's summer now and I want to enjoy it, I only have time for fixing critical bugs, but not for new features.
Maybe in the fall I can think about what new and useful things can be added.

[vralle]

I think so.

I was able to quickly integrate frontmatter for pages, but extracting frontmatter from template parts (such as content files in MD/MDX format) to use the data in a parent template seems like a very tricky task.

preprocessor: (content, { data }) => {
  if (frontmatter.test(content)) {
    const fm = frontmatter.extractor(content);
    return eta.renderString(fm.body, { ...data, frontmatter: fm.frontmatter });
  }
  return eta.renderString(content, data);
},

[vralle]

@webdiscus, I’ve started a project using a plugin and Nunjucks.
I’d like to use {% include "file.md" %} in my templates.
Would you be able to advise on the best strategy for parsing Markdown files?
Is it better to handle this through a Markdown loader or via Nunjucks (using filters or custom tags or something else)?

[webdiscus]

@vralle try the experimental version 4.22.0-alpha.0.
See the usage in the test case: nunjucks-extension-markdown.

Note: it's only very quick experimental prototype. Later I will add supporting markdown-it options in all preprocessors.

[webdiscus]

P.S.: In summer I can be very slow because I am on vacation.

[vralle]

Nunjucks code is like a TV show with a tangled - plot everything seems straightforward at first, until you peek under the hood and realize it's a full-blown drama starring Loaders, Contexts, and CallExtensions. It's a bit messy, sure, but somehow it works like a beautifully disorganized masterpiece that just refuses to fall apart)

I'll try 4.22.0-alpha.0

[webdiscus]

Unfortunately Nunjucks is not maintained more :-(

[vralle]

The problem with template engines lies in the isolation of their ecosystems.
They are not integrated into the environment where a developer works daily: VSCode, TypeScript, CI/CD, linting, devtools...

Template Engines vs JSX/TSX

JSX/TSX isn't just a syntax. It's an ecosystem:

• Language Server Protocol (LSP), autocompletion, interactive error messages
• Type-checking through TypeScript
• Full integration with devtools, hot reload, eslint, prettier, etc.

Template Engines:

• No full-fledged LSP support
• No inline type checking in templates
• No component or parameter autocompletion
• Documentation is fragmented or outdated

Nunjucks doesn't even have its own type definitions. The few ones available in @types/nunjucks don't really solve the problem.