This repo is forked from https://github.com/RyanCavanaugh/project-references-demo. It is to test project references with webpack, ts-loader and ForkTsCheckerWebpackPlugin.
It could be used as an example of how to use project references with ts-loader, although I would not claim that this is the only or even best way to set up a project. I like to use yarn workspaces to organise my project and I will create an example showing this, but I would not want to imply that yarn workspaces are a requirement to use project references.
With projectReferences = false the build will fail unless the references are pre-built:
yarn clean
npx webpack <- Module not found: Error: Can't resolve '../lib/zoo/zoo'
tsc -b
npx webpack <- OK
With projectReferences = true ts-loader will build the references at the start of the build:
yarn clean
npx webpack <- OK
If a change is made to src/index.ts and npx webpack run again, the change will be reflected in the final output dist/main.js
If a change is made to zoo/zoo.ts and npx webpack run again, the change will be reflected in both lib/zoo/zoo.js and the final output. ts-loader causes the references to be rebuilt because they were out of date.
If an error is introduced in src/index.ts the error not be reported when npx webpack is run:
console.log(newZoo[0].namex);
If an error is introduced in animals/dog.ts the error will be reported when npx webpack is run and lib/animals/dog.ts will not be updated. transpileOnly will only affect files processed by directly ts-loader. ts-loader will initiate the build of referenced projects but any errors will be reported despite transpileOnly being set. This behaviour is expected.
If the same error is introduced in src/index.ts the error will be reported when npx webpack is run. This is as expected as transpileOnly in ts-loader turns off syntax checking and ForkTsCheckerWebpackPlugin turns it on again.
It is not clear to me what effect project references has on ForkTsCheckerWebpackPlugin. The documentation says they are supported, but errors in project references will cannot be turned off by ts-loader, so they will be reported anyway. I don't understand in what sense ForkTsCheckerWebpackPlugin is supporting project references but I also don't see any bug here.
I do notice that in watch mode after yarn clean I see the following output in watch mode:
Issues checking in progress...
Issues checking in progress...
Issues checking in progress...
Issues checking in progress...
On the next run I only see one line. So it looks as if ForkTsCheckerWebpackPlugin is checking each of the project references. As they will already be checked when ts-loader initiates the build this seems to be a duplicated effort, although as ForkTsChecker runs on a separate thread it probably does not affect performance.
Setting watch: true in webpack.config.js works as you would expect.
After making changes to files the changes are reflected in the final output and in lib (if a project reference file is changed). If transpileOnly is true errors in src/index.ts are not reported unless ForkTsCheckerWebpackPlugin is enabled, in which case they are.
This is a limited example but I believe webpack, ts-loader, ForkTsCheckerWebpackPlugin are all behaving as expected with project references.
With webpack-dev-server, once the initial build is complete, changes to src/index.ts are built within 100ms. In larger projects this will be longer but it seems webpack and ts-loader do a great job and can rebuild after a single file change in less than a second.
Making a change in animals/dog.ts causes 2 compilations. The first is the compilation of the reference which takes around 1 second and the second compilation is less than 100ms when the project is rebuilt using the new output in lib. With webpack-dev-server both compilations are reported in the webpack log. With webpack and watch: true only the second compilation is reported although a delay of around 1 second is noticeable before the second compilation starts.
If you turn off projectReferences in ts-loader and execute tsc -b -w in a different shell, the effect is the same. You can see tsc -b -w takes around 1 second to compile the reference and then webpack builds the project. This is as expected because, under the hood, ts-loader is just using tsc to build the referenced projects. It is just more convenient than having to run tsc separately.
This is a tiny project. It is possible that with a larger project there will be a significant performance difference, but from this repo ts-loader appears to be behaving as expected. To see the performance with a large codebase checkout the benchmark branch of this repo.
I have not considered startup time here. I believe running tsc in a separate process could provide some benefit there for larger projects.