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

Start with the optional-extension documentation and examples, then compare their CSS-loading guidance with the Symfony Asset Mapper documentation linked in the issue. Update the relevant examples or notes to show that CSS uses a static top-level import, and confirm the guidance covers bundler-free setups without changing the conditional JavaScript loading pattern.

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.