@travetto/compiler
v5.0.16
Published
The compiler infrastructure for the Travetto framework
Downloads
909
Readme
Compiler
The compiler infrastructure for the Travetto framework
Install: @travetto/compiler
npm install @travetto/compiler
# or
yarn add @travetto/compiler
This module expands upon the Typescript compiler, with the additional features:
- Integration with the Transformation module, allowing for rich, type-aware transformations
- Automatic conversion to either Ecmascript Module or CommonJS based on the Package JSON
type
value - Removal of type only imports which can break Ecmascript Module-style output
- Automatic addition of
.js
extension to imports to also support Ecmascript Module-style output Beyond the Typescript compiler functionality, the module provides the primary entry point into the development process.
CLI
The compiler cli, trvc is the entry point for compilation-related operations. It has the ability to check for active builds, and ongoing watch operations to ensure only one process is building at a time. Within the framework, regardless of mono-repo or not, the compilation always targets the entire project. With the efficient caching behavior, this leads to generally a minimal overhead but allows for centralization of all operations.
The compiler cli supports the following operations:
start|watch
- Run the compiler in watch modestop
- Stop the compiler if runningrestart
- Restart the compiler in watch modebuild
- Ensure the project is built and upto dateclean
- Clean out the output and compiler cachesinfo
- Retrieve the compiler information, if runningevent <log|progress|state>
- Watch events in realtime as newline delimited JSONexec <file> [...args]
- Allow for compiling and executing an entrypoint filemanifest --prod [output]
- Generate the project manifest In addition to the normal output, the compiler supports an environment variableTRV_BUILD
that supports the following values:debug
,info
,warn
ornone
. This provides different level of logging during the build process which is helpful to diagnose any odd behaviors. When invoking an unknown command (e.g.<other>
from above), the default level iswarn
. Otherwise the default logging level isinfo
.
Terminal: Sample trv output with debug logging
$ TRV_BUILD=debug trvc build
2029-03-14T04:00:00.618Z info [server ] Starting server http://127.0.0.1:25539
2029-03-14T04:00:00.837Z debug [main ] Start Server
2029-03-14T04:00:01.510Z debug [event-stream ] Started event stream
2029-03-14T04:00:02.450Z debug [precompile ] Started
2029-03-14T04:00:02.762Z debug [precompile ] Skipped @travetto/manifest
2029-03-14T04:00:02.947Z debug [precompile ] Skipped @travetto/transformer
2029-03-14T04:00:03.093Z debug [precompile ] Skipped @travetto/compiler
2029-03-14T04:00:04.003Z debug [precompile ] Completed
2029-03-14T04:00:04.495Z debug [manifest ] Started
2029-03-14T04:00:05.066Z debug [manifest ] Completed
2029-03-14T04:00:05.307Z debug [transformers ] Started
2029-03-14T04:00:05.952Z debug [transformers ] Skipped @travetto/cli
2029-03-14T04:00:06.859Z debug [transformers ] Skipped @travetto/runtime
2029-03-14T04:00:07.720Z debug [transformers ] Skipped @travetto/schema
2029-03-14T04:00:08.179Z debug [transformers ] Completed
2029-03-14T04:00:08.588Z debug [delta ] Started
2029-03-14T04:00:09.493Z debug [delta ] Completed
2029-03-14T04:00:10.395Z debug [manifest ] Started
2029-03-14T04:00:10.407Z debug [manifest ] Wrote manifest @travetto-doc/compiler
2029-03-14T04:00:10.799Z debug [manifest ] Completed
2029-03-14T04:00:11.013Z info [server ] State changed: compile-end
2029-03-14T04:00:11.827Z debug [compiler-exec ] Skipped
2029-03-14T04:00:11.894Z debug [event-stream ] Finished event stream
2029-03-14T04:00:12.133Z info [server ] Closing down server
2029-03-14T04:00:13.123Z debug [server ] Server close event
2029-03-14T04:00:14.014Z info [server ] Closed down server
2029-03-14T04:00:14.924Z debug [server ] Finished processing events
2029-03-14T04:00:15.690Z debug [main ] End Server
Terminal: Sample trv output with default log level
$ trvc build
Compilation Architecture
The compiler will move through the following phases on a given compilation execution:
Bootstrapping
- Initial compilation of Compiler'ssupport/*.ts
filesCompiler Server
- Provides a simple HTTP interface to watching compiler file and state changes, and synchronizing multiple processesBuild Compiler
- Leverages Typescript to build files needed to execute compilerBuild Manifest
- Produces the manifest for the given executionBuild Transformers
- Leverages Typescript to compile all transformers defined in the manifestProduce Manifest Delta
- Compare the output file system with the manifest to determine what needs to be compiledClear all output if needed
- When the compiler source or transformers change, invalidate the entire outputPersist Manifest(s)
- Ensure the manifest is available for the compiler to leverage. Multiple will be written if in a monorepoInvoke Compiler
- Run Typescript compiler with the aforementioned enhancements
Bootstrapping
Given that the framework is distributed as Typescript only files, there is a bootstrapping problem that needs to be mitigated. The trvc entrypoint, along with a small context utility in Manifest are the only Javascript files needed to run the project. The trvc entry point will compile @travetto/compiler/support/*
files as the set that is used at startup. These files are also accessible to the compiler as they get re-compiled after the fact.