Loading only the extensions you use

By default, the datatable Stimulus controller imports every DataTables package it can use: the core in each of four styles, all ten extensions in each style, JSZip, pdfmake, Lucide and Bootstrap. A bundler or an import map ships all of them, even when your tables only use paging and search.

Registered package loading inverts this. The datatable_core controller imports nothing but @hotwired/stimulus, and your application registers the packages it uses with packageLoaders. A package you do not register is never requested.

Run the install command

php bin/console ux-datatables:install --style=tailwind buttons responsive select

Extensions are arguments: buttons, colReorder, columnControl, fixedColumns, fixedHeader, keyTable, responsive, rowGroup, scroller, searchBuilder and select. Pass none to pick them interactively, or --all to select every one.

php bin/console ux-datatables:install --style=tailwind buttons responsive select
php bin/console ux-datatables:install --style=tailwind --prune buttons responsive select
php bin/console cache:clear

php bin/console ux-datatables:install --style=tailwind buttons responsive select
# Run the install line the command prints, for example:
npm install datatables.net-dt@3.1.3 datatables.net-buttons-dt@4.1.2 ...
npm run watch

The command is idempotent. To change the selection, run it again with the new list of extensions.

What it writes

For buttons, the command also registers JSZip and pdfmake. They load only when a table has an excel or pdf button. Lucide is always registered, because icon columns and empty states use it and the command cannot detect them.

Styles

Bootstrap 3 and 4 are not offered. See Styling.

Pruning the import map

--prune removes the datatables.net*, jszip and pdfmake JavaScript entries from importmap.php that you did not register. It never touches bootstrap or lucide, because your application may import them itself, and it leaves CSS entries alone: with missing_import_mode: strict, removing a stylesheet that the 1.x loaders still mention makes asset-map:compile fail.

Manual setup

You do not need the command. Three files carry the whole setup.

1. Select the controller in config/packages/data_tables.yaml

   data_tables:
       package_loading: registered # builtin | registered

   In debug mode, an explicit value that contradicts assets/controllers.json fails the container build, instead of rendering a controller nobody registered.

2. Enable datatable_core in assets/controllers.json

   {
       "controllers": {
           "@pentiminax/ux-datatables": {
               "datatable": {
                   "enabled": false
               },
               "datatable_core": {
                   "enabled": true,
                   "fetch": "eager",
                   "autoimport": {
                       "@pentiminax/ux-datatables/dist/styles/datatables-base-style.css": true,
                       "@pentiminax/ux-datatables/dist/styles/datatables-tailwind-theme.css": true,
                       "datatables.net-dt/css/dataTables.dataTables.min.css": true,
                       "datatables.net-bs5/css/dataTables.bootstrap5.min.css": false
                   }
               }
           }
       },
       "entrypoints": []
   }

3. Register the packages in assets/datatables.js

   Import it first from assets/stimulus_bootstrap.js (or assets/bootstrap.js), before startStimulusApp():

   import './datatables.js'
   import { startStimulusApp } from '@symfony/stimulus-bundle'
   
   startStimulusApp()

   import { packageLoaders } from '@pentiminax/ux-datatables/dist/core.js'
   
   packageLoaders
       .register('dataTables', () => import('datatables.net-dt'))
       .register('select', () =>
           Promise.all([
               import('datatables.net-select-dt'),
               import('datatables.net-select-dt/css/select.dataTables.min.css'),
           ]))

A loader imports both the JavaScript and the stylesheet its package needs, and you choose the style by choosing the package (datatables.net-select-bs5 instead of -dt). Two packages need an extra import: searchBuilder must import datatables.net-datetime first, and pdfmake must import pdfmake/build/vfs_fonts.js.

With AssetMapper, add the dist/core.js entry and install the packages:

php bin/console importmap:require @pentiminax/ux-datatables/dist/core.js \
    --path=./vendor/pentiminax/ux-datatables/assets/dist/core.js
php bin/console importmap:require datatables.net-dt datatables.net-select-dt \
    datatables.net-dt/css/dataTables.dataTables.min.css \
    datatables.net-select-dt/css/select.dataTables.min.css

With Encore, run npm install for the same packages.

The “package is not registered” error

A table that needs a package you did not register fails with:

The "select" package is not registered. Install it and register it with packageLoaders.register('select', loader).

The package name is the first argument of register(). Fix it by running the install command with the missing extension added to the list, or by adding the register() call to assets/datatables.js by hand. A table that enables an extension through its PHP model (select(), responsive(), buttons()) needs that extension registered.

JSZip and pdfmake are optional and never raise this error. Without them, Buttons loads without Excel and PDF support, and DataTables silently leaves out the excel and pdf buttons.

Third-party extensions

Registering an extension the bundle does not know is not supported in 1.5. The registry accepts a closed list of names: dataTables, buttons, jszip, pdfmake, bootstrap, lucide, colReorder, columnControl, fixedColumns, fixedHeader, keyTable, responsive, rowGroup, scroller, searchBuilder and select.