DOC-3367: Add new bundling guide overview page. by kemister85 · Pull Request #3983 · tinymce/tinymce-docs

kemister85 · 2026-02-12T00:07:09Z

Ticket: DOC-3367

Site: New: Bundling guide (page)

Summary

Adds a new bundling overview guide and improves bundling documentation consistency across the codebase.

Changes

New Files

modules/ROOT/pages/bundling-guide.adoc - New bundling overview page providing:
- Overview of bundling TinyMCE with module bundlers (Webpack, Vite, Rollup, Browserify)
- Required imports (TinyMCE core, silver theme, dom model, default icons, skins, content CSS)
- Plugin import syntax for community and premium plugins
- Plugin gotchas (plugins requiring additional resources, plugin dependencies)
- CSS files information
- Language files information
- Links to all related bundling reference pages
60 plugin feature pages - Added include::partial$misc/bundling-guide-link.adoc[] to all core and premium plugins.

Pre-checks:

Branch prefixed with feature/<version>/, hotfix/<version>/, staging/<version>/, or release/<version>/.
modules/ROOT/nav.adoc has been updated (if applicable).

Review:

Documentation Team Lead has reviewed

metricjs · 2026-02-13T03:34:48Z

modules/ROOT/pages/bundling-guide.adoc

+
+== Plugin gotchas
+
+Some plugins require additional resource files (JS, CSS, or language files) to function properly. These must be explicitly imported when bundling:


Suggested change

Some plugins require additional resource files (JS, CSS, or language files) to function properly. These must be explicitly imported when bundling:

Some plugins require additional resource files (JS, CSS, or language files) to function properly. These must be explicitly imported when bundling.

?

metricjs · 2026-02-13T03:35:46Z

modules/ROOT/pages/bundling-guide.adoc

+
+* Core plugin resources typically use relative paths without file extensions
+* Premium plugin resources (from `+tinymce-premium+`) MUST include the `.js` or `.css` file extension in the import path
+* Plugins lazy-load additional resources at runtime, so these files must be included in the bundle or accessible as static assets


"Some plugins" or "plugins may" - to not cause panic that every plugin pulls in more resources?

metricjs · 2026-02-13T03:37:34Z

modules/ROOT/pages/bundling-guide.adoc

+Key points about plugin resources:
+
+* Core plugin resources typically use relative paths without file extensions
+* Premium plugin resources (from `+tinymce-premium+`) MUST include the `.js` or `.css` file extension in the import path


I can't see this noted in Sorita's notes and wasn't aware it was a thing - sanity checking where this comes from?

Oh, was this from her examples for the lang files?

I think we may not need to include this. An integrator could follow their own import styles, so long as their bundler is configured properly to resolve the file extensions. The choices in the example code were mainly to ensure it would work for the majority out of the box.

metricjs · 2026-02-13T03:39:58Z

modules/ROOT/pages/bundling-guide.adoc

+
+== CSS files
+
+Plugin CSS files are typically included automatically when importing plugins. However, some plugins may require explicit CSS imports for proper styling.


Suggested change

Plugin CSS files are typically included automatically when importing plugins. However, some plugins may require explicit CSS imports for proper styling.

Some plugins require additional CSS files. Plugin CSS files are included automatically when importing plugins via their JS file.

or something? from what Sorita said, should never need to pull in a CSS file manually

Currently, there aren't any plugins that require a CSS import, and if it does, then it would likely require a fix - as in the case for Uploadcare.

metricjs · 2026-02-13T03:41:09Z

modules/ROOT/pages/bundling-guide.adoc

+Language files are optional and used for localizing the {productname} UI and plugin interfaces.
+
+=== Core UI language files
+


Suggested change

For community packages:

metricjs · 2026-02-13T03:42:39Z

modules/ROOT/pages/bundling-guide.adoc

+[NOTE]
+====
+* English is the default language, so `+en.js+` language files don't exist
+* For premium plugins, the language file path must include the `.js` extension


From the examples here, it looks like the .js is always required, whether premium or community? @soritaheng any thoughts?

Most bundlers support resolving file extensions, so they are not necessarily required. For example, in Vite. Since the order of the resolution could be configured, I went with the extensions in the examples for clarity's sake. But let me know if that should be reconsidered.

soritaheng · 2026-02-19T06:31:22Z

modules/ROOT/pages/bundling-guide.adoc

+
+* **Emoticons**: Requires an emoji database file (`+js/emojis+`)
+* **Help**: Requires a keyboard navigation language file (`+js/i18n/keynav/<lang>+`)
+* **Page Embed**: Requires a CSS file (`+css/empa30.css+`)


From my testing, this import is not necessary. Was there an issue reported on page embed that required this import?

soritaheng · 2026-02-19T06:34:39Z

modules/ROOT/pages/bundling-guide.adoc

+
+=== Plugins requiring additional resources
+
+* **Emoticons**: Requires an emoji database file (`+js/emojis+`)


Suggested change

* **Emoticons**: Requires an emoji database file (`+js/emojis+`)

* **Emoticons**: Requires an emoji database file (`+js/emojis.js+`)

soritaheng · 2026-02-19T06:35:23Z

modules/ROOT/pages/bundling-guide.adoc

+=== Plugins requiring additional resources
+
+* **Emoticons**: Requires an emoji database file (`+js/emojis+`)
+* **Help**: Requires a keyboard navigation language file (`+js/i18n/keynav/<lang>+`)


Suggested change

* **Help**: Requires a keyboard navigation language file (`+js/i18n/keynav/<lang>+`)

* **Help**: Requires a keyboard navigation language file (`+js/i18n/keynav/<lang>.js+`)

soritaheng · 2026-02-19T06:44:03Z

modules/ROOT/pages/bundling-guide.adoc

+// Community plugin language file
+import 'tinymce/plugins/<plugincode>/langs/<language>.js';
+
+// Premium plugin language file (note: .js extension required)


Suggested change

// Premium plugin language file (note: .js extension required)

// Premium plugin language file

We can remove this

soritaheng · 2026-02-19T06:48:17Z

modules/ROOT/pages/bundling-guide.adoc

+
+=== Plugin language files
+
+Plugin language files are separate from the main UI language files:


I think we should also note that the editor's language option must first be set to the desired language for the plugin's language file to take effect.

soritaheng · 2026-02-19T07:10:08Z

modules/ROOT/pages/bundling-guide.adoc

+
+[NOTE]
+====
+* English is the default language, so `+en.js+` language files don't exist


Maybe worth specifying it's US English? https://www.tiny.cloud/docs/tinymce/latest/ui-localization/#language. Perhaps also mentioning language packs for extra clarity, as help and autocorrect plugins have an en.js file.

Suggested change

* English is the default language, so `+en.js+` language files don't exist

* US English is the default language, so the language packs do not include `+en.js+` language files

soritaheng · 2026-02-19T07:14:49Z

modules/ROOT/pages/bundling-guide.adoc

+* Icons, see xref:bundling-icons.adoc[Bundling icons]
+* Themes, see xref:bundling-themes.adoc[Bundling themes]
+* Models, see xref:bundling-models.adoc[Bundling models]
+* Skins, see xref:bundling-skins.adoc[Bundling skins]


The page for Bundling skin mainly references CSS files. @metricjs I think for guides like Webpack and Browserify that already have ways to import CSS files, it may be worth keeping those examples around. We could consider adding a note that importing the js file is another way to get the CSS, but it seems safest not to remove those CSS examples when we start tackling those specific pages.

DOC-3367: Add new bBundling guide overview page.

097dc65

kemister85 requested review from a team, jscasca, kimwoodfield, metricjs, soritaheng and tiny-ben-tran and removed request for a team February 12, 2026 00:13

kemister85 marked this pull request as ready for review February 12, 2026 00:13

kemister85 requested a review from a team as a code owner February 12, 2026 00:13

kemister85 requested review from EkimChau, ShiridiGandham and tiny-james February 12, 2026 00:13

metricjs reviewed Feb 13, 2026

View reviewed changes

soritaheng reviewed Feb 19, 2026

View reviewed changes


		== Plugin gotchas

		Some plugins require additional resource files (JS, CSS, or language files) to function properly. These must be explicitly imported when bundling:


		== CSS files

		Plugin CSS files are typically included automatically when importing plugins. However, some plugins may require explicit CSS imports for proper styling.

	Plugin CSS files are typically included automatically when importing plugins. However, some plugins may require explicit CSS imports for proper styling.
	Some plugins require additional CSS files. Plugin CSS files are included automatically when importing plugins via their JS file.

		Language files are optional and used for localizing the {productname} UI and plugin interfaces.

		=== Core UI language files


		=== Plugins requiring additional resources

		* Emoticons: Requires an emoji database file (`+js/emojis+`)

	* Help: Requires a keyboard navigation language file (`+js/i18n/keynav/<lang>+`)
	* Help: Requires a keyboard navigation language file (`+js/i18n/keynav/<lang>.js+`)

	// Premium plugin language file (note: .js extension required)
	// Premium plugin language file


		=== Plugin language files

		Plugin language files are separate from the main UI language files:

	* English is the default language, so `+en.js+` language files don't exist
	* US English is the default language, so the language packs do not include `+en.js+` language files

Conversation

kemister85 commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New Files

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

kemister85 commented Feb 12, 2026 •

edited

Loading