Dynamic CSS import via await import() fails silently with Symfony Asset Mapper

[tacman]

Summary

When integrating DataTables ColumnControl (or other extensions) with Symfony Asset Mapper, the recommended pattern of dynamically importing CSS inside an async try/catch block silently fails — the CSS is never loaded.

Pattern that fails

try {
  await import('datatables.net-columncontrol-bs5');
  await import('datatables.net-columncontrol-bs5/css/columnControl.bootstrap5.min.css');
  dtPlugins.columnControl = true;
} catch (error) {
  console.warn('ColumnControl unavailable', error);
}

Symfony Asset Mapper uses native ES modules and a static importmap. It only processes static top-level import statements at build time. Dynamic import() expressions inside async functions are not analysed for CSS, so the CSS file is never injected into the page.

The JS loads fine (the extension initialises), but without its stylesheet the controls render incorrectly — in our case, the ColumnControl search input was invisible because none of the dtcc-* CSS rules were applied.

Fix

Move the CSS import to a static top-level import, separate from the conditional JS load:

// Static — processed by Asset Mapper at build time
import 'datatables.net-columncontrol-bs5/css/columnControl.bootstrap5.min.css';

// Dynamic — still fine for JS (optional/conditional loading)
try {
  await import('datatables.net-columncontrol-bs5');
  dtPlugins.columnControl = true;
} catch (error) {
  console.warn('ColumnControl unavailable', error);
}

Context

• Symfony Asset Mapper: https://symfony.com/doc/current/frontend/asset_mapper.html
• Uses a static importmap.json / importmap.php — no bundler (webpack/vite)
• Dynamic CSS imports work fine with Vite/webpack but not with Asset Mapper
• The extension JS loads correctly; only CSS is affected

Suggestion

The docs/examples for optional extensions could note that CSS imports must be static when using bundler-free setups like Symfony Asset Mapper, or provide a <link> tag fallback alongside the JS example.

[AllanJard]

Interesting one. This doesn't sound like something that I can address in my CSS file or bundle, but rather the issue is that if you do a static import it will import both JS and CSS from the package, but if you use a dynamic import, it imports only the JS.

I can certainly see being a footgun, but I feel like it is probably something that the bundler needs to make clear in their documentation, rather than in the DataTables docs. I don't really want to add extra clauses for each bundler unless necessary. Will leave open to see how the Symfony team reply to your issue on their repo. I suspect that the dynamic import uses the browser native dynamic import and since there isn't any package information on the client-side, it isn't something that can be resolved.

[tacman]

I'm fighting something where I can see a flash of what I think is the columnControl widgets, but then the display is wrong.

This is called at the top of my stimulus controller.

import { dtPlugins } from "../datatables-plugins.js";
import PerfectScrollbar from "perfect-scrollbar";
import enLanguage from "datatables.net-plugins/i18n/en-GB.mjs";
import esLanguage from "datatables.net-plugins/i18n/es-ES.mjs";
import deLanguage from "datatables.net-plugins/i18n/de-DE.mjs";

This is the plugins:

import 'datatables.net-select-bs5';
import 'datatables.net-searchpanes-bs5';
import 'datatables.net-searchbuilder-bs5';
import 'datatables.net-buttons-bs5';
import 'datatables.net-responsive-bs5';
import 'datatables.net-scroller-bs5';

import 'datatables.net-bs5/css/dataTables.bootstrap5.min.css';
import 'datatables.net-searchpanes-bs5/css/searchPanes.bootstrap5.min.css';
import 'datatables.net-searchbuilder-bs5/css/searchBuilder.bootstrap5.min.css';
import 'datatables.net-responsive-bs5/css/responsive.bootstrap5.min.css';
import 'datatables.net-scroller-bs5/css/scroller.bootstrap5.min.css';
import 'datatables.net-buttons-bs5/css/buttons.bootstrap5.min.css';
import 'datatables.net-columncontrol-bs5/css/columnControl.bootstrap5.min.css';

export const dtPlugins = {
  columnControl: false,
};

try {
  console.warn('importing columncontrol');
  await import('datatables.net-columncontrol-bs5');
  dtPlugins.columnControl = true;
} catch (error) {
  console.warn('[api-grid] ColumnControl plugin unavailable; falling back without it.', error);
}

Of course, the whole false until after await import then true smells!

[AllanJard]

Given that it is a dynamic import, you are probably getting a Flash Of Unstyled Content (FOUC) - the Javascript runs before the CSS has been loaded - thus giving rise to what you are seeing.

You either need to have the Javascript initialisation wait until the CSS has been loaded, or have the CSS as part of the static bundle.

[tacman]

right, but then it's not working. It's not the flash. Any suggestions on how to debug this?

[AllanJard]

Other than checking that the CSS has actually been loaded in the network browser and the DOM inspector - not really I'm afraid. I've not made use of AssetManager before myself, so I don't know much about it. Possibly it is scoping the CSS (but I doubt it)...

[tacman]

Sigh. I use tabler (tabler.io) which is based on bootstrap, but uses its own classes (tblr- instead of bs-).

Our designer found the issue. tabler uses its own --tblr- prefix for css vars instead of standard --bs- prefix. and datatables/bootstrap css cannot find --bs- css vars. therefore the css was not being applied.

now, the proper solution for us is to re-write those css from datatables which uses --bs- and replace it with --tblr.

for example:

--dtcc-search-input_background: var(--bs-body-bg); // actual datatables css

replace it with

--dtcc-search-input_background: var(--tblr-body-bg);

Ideas on how to solve this? Because replicating the .bs5 plugins with .tlbr files?

[AllanJard]

The DataTables Bootstrap 5 CSS files assume that the --bs- variables will be present. If they aren't (I assume tabler.io removes them and replaces with its own?), then you'd need to do something like:

:root {
  --bs-body-bg: --tblr-body-bg;
  ...
}

Its that or create a new styling integration for DataTables specifically for tabler.io.