Battle scarred developer's guide to Umbraco v17 - Bundles

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

With the Early adopters guide we talked about Entry points as the start of your front end code journey, but now with a few tweaks since v14 bundles are where it's at.

What's a bundle.

A bundle is an extension point in Umbraco's Backoffice that lets you load JavaScript files and register manifests inside Umbraco's system so your code is loaded as part of the Backoffice.

Put simply it's the loader of your extension.

typically your entry point javascript file will only import manifest from around your project and return them for umbraco to ingest.

export const manifests: Array<UmbExtensionManifest> = [
  ...entrypoints,
  ...sectionManifests,
  ...dashboardManifests,
  ...localizationManifests,
  ...menuManifests,
  ...workspaceManifests,
  ...editorManifests,
  ...modalManifests,
];

As your project grows so will this list, to keep it simple and organised i would recommend that at each level you have manifest that might also import from child folders, before finally having everything brought into the bundle file.

For example in the DoStuffWithUmbraco repository. we might have a /workspaces/views/manfiest.ts file, that is then imported into the /workspace/manifest.ts file which is the one we import into our bundle file.

+-- src
  - bundle.manifest.ts
  +-- workspaces
    - manifest.ts
    +-- views
      - manifest.ts  

This means everything needed for the workspace is in /workspace/manifest.ts and we can if need be move it about knowing it's all there. It also means any one manifest definition file doesn't contain two much information.

What about manifests in umbraco-package.json

There is quite a bit in the umbraco docs about how you can define your manifests inside the umbraco-package.json file, and you can, but once you go beyond something very very basic (e.g. not just adding localization). you will want to do it via a bundle.

Adding all the manifests via the bundle gives you better typescript & checking support in your project, its neater and it catches the errors quicker.

Adding via the umbraco-package.json also requires that the site be restarted for the packages to be loaded (these files are read in by the Backoffice code on start-up). using a bundle as the entry point you can add new things build the scripts and it all appears.