One of the most exciting features to ship with TypeScript 2.4 was support for the dynamic import expression. To quote the release blog post:
importexpressions are a new feature in ECMAScript that allows you to asynchronously request a module at any arbitrary point in your program. These modules come back as
Promises of the module itself, and can be
await-ed in an async function, or can be given a callback with
Many bundlers have support for automatically splitting output bundles (a.k.a. “code splitting”) based on these
import()expressions, so consider using this new feature with the
esnextmodule target. Note that this feature won’t work with the
es2015module target, since the feature is anticipated for ES2018 or later.
As the post makes clear, this adds support for a very bleeding edge ECMAScript feature. This is not fully standardised yet; it's currently at stage 3 on the TC39 proposals list. That means it's at the Candidate stage and is unlikely to change further. If you'd like to read more about it then take a look at the official proposal here.
Whilst this is super-new, we are still able to use this feature. We just have to jump through a few hoops first.
First of all, you need to install TypeScript 2.4. With that in place you need to make some adjustments to your
tsconfig.json in order that the relevant compiler switches are flipped. What do you need? First of all you need to be targeting ECMAScript 2015 as a minimum. That's important specifically because ES2015 contained
Promises which is what dynamic
imports produce. The second thing you need is to target the module type of
esnext. You're likely targeting
esnext is that plus dynamic
tsconfig.json I made earlier which has the relevant settings set:
At the time of writing, browser support for dynamic
import is non-existent. This will likely be the case for some time but it needn't hold us back. Babel can step in here and compile our super-new JS into JS that will run in our browsers today.
You'll need to decide for yourself how much you want Babel to do for you. In my case I'm targeting old school browsers which don't yet support ES2015. You may not need to. However, the one thing that you'll certainly need is the Syntax Dynamic Import plugin. It's this that allows Babel to process dynamic
These are the options I'm passing to Babel:
You're also going to need something that actually execute the
imports. In my case I'm using webpack...
webpack 2 supports
import(). So if you webpack set up with ts-loader (or awesome-typescript-loader etc), chaining into babel-loader you should find you have a setup that supports dynamic
import. That means a
webpack.config.js that looks something like this:
I'm one of the maintainers of ts-loader which is a TypeScript loader for webpack. When support for dynamic
imports landed I wanted to add a test to cover usage of the new syntax with ts-loader.
We have 2 test packs for ts-loader, one of which is our "execution" test pack. It is so named because it works by spinning up webpack with ts-loader and then using karma to execute a set of tests. Each "test" in our execution test pack is actually a mini-project with its own test suite (generally jasmine but that's entirely configurabe). Each complete with its own
karma.conf.js and either a
package.json for bringing in dependencies. So it's a full test of whether code slung with ts-loader and webpack actually executes when the output is plugged into a browser.
This is the test pack for dynamic
As you can see, it's possible to use the dynamic
import as a
Promise directly. Alternatively, it's possible to consume the imported module using TypeScripts support for
await. For my money the latter option makes for much clearer code.
If you're looking for a complete example of how to use the new syntax then you could do worse than taking the existing test pack and tweaking it to your own ends. The only change you'd need to make is to strip out the
resolveLoader statements in
karma.conf.js. (They exist to lock the test in case to the freshly built ts-loader stored locally. You'll not need this.)
You can find the test in question here. Happy code splitting!