22. DataTables project file names

One of the great challenges of maintaining any complex project is that of organisation and DataTables is no exception. The project is primarily split between the core DataTables library, extensions, and plug-ins. This tech note attempts to codify the rules that are used to define the file names for the various files for DataTables and its extensions (there are a lot of them!).

It is important to note that it is not just the the software module that we need to take account of with the file name, but also:

• The styling framework integration (e.g. DataTables default, Bootstrap, Bulma, etc)
• Whether the file is minified or not
• The file type:
  • ES Module: .mjs
  • UMD loader: .js
  • CSS: .css

File name rules

With that in mind, this is how we define the rules of the file names in the DataTables distribution packages:

1. File names are hierarchical, with the most significant software name on the left
2. Each plug-in adds its own name to the hierarchy (on the right), unless it is identical the previous item in the hierarchy
3. DataTables is top of the hierarchy tree
4. The hierarchy is dot separated
5. The file name is limited to just the last two elements in the hierarchy.
6. Styling framework integration files have the framework name appended as the last element in the hierarchy
7. DataTables provided styles count as a framework (the Javascript defaults are suited for their style framework)
8. The extension .min is used to represented a minified file (appended before the file extension)
9. The file name will always have an extension (e.g. .css, .js, .mjs).
10. The file name is camelCase - i.e. all lower-case except where two words have been combined

Examples

Let's work through a few examples to see this in practice.

DataTables

DataTables is the base so we have simply:

File function	Hierarchy	File name
Core JS library	DataTables	dataTables.js
Bootstrap 5 JS	DataTables > Bootstrap 5	dataTables.bootstrap5.js
Bulma CSS	DataTables > Bulma	dataTables.bulma.css

Obviously there are a lot of other files, plus their minified variants. And now you see why we need to the time to come up with something as boring as a naming convention for the files!

Editor

With Editor we are adding another layer to the hierarchy, so we start to see the effect of rule 5, limiting the name to just the last two elements:

File function	Hierarchy	File name
Editor JS	DataTables > Editor	dataTables.editor.js
Bootstrap 5 JS	DataTables > Editor > Bootstrap 5	editor.bootstrap5.js
DataTables default CSS	DataTables > Editor > DataTables	editor.dataTables.css

etc.

A note on ES modules (.mjs)

We provide support for number of different ways to load Javascript into your projects:

• Via a Universal Module Description (UMD), which supports:
  • AMD
  • CommonJS
  • Direct loading in the browser
• Via EcmaScript Modules (ESM)

It is not possible to include an ESM loader along with a UMD in a single file, so we must provide two files for each piece of Javascript we want to publish. To distinguish between them, we follow the V8 guidelines and use .mjs to indicate that a file contains ESM loader code, and .js for UMD loader code. Node and package builders will automatically use the file that they require based on these extensions.