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 mode
• stop - Stop the compiler if running
• restart - Restart the compiler in watch mode
• build - Ensure the project is built and upto date
• clean - Clean out the output and compiler caches
• info - Retrieve the compiler information, if running
• event <log|progress|state> - Watch events in realtime as newline delimited JSON
• exec <file> [...args] - Allow for compiling and executing an entrypoint file
• manifest [output] - Generate the project manifest
• manifest:production [output] - Generate the production project manifest

In addition to the normal output, the compiler supports an environment variable TRV_BUILD that supports the following values: debug, info, warn or none. 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 is warn. Otherwise the default logging level is info.

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 [compiler-exec  ] Start Server
2029-03-14T04:00:01.510Z debug [event-stream   ] Started event stream
2029-03-14T04:00:02.450Z info  [compiler-exec  ] Launching compiler
2029-03-14T04:00:02.762Z debug [server         ] Compilation started
2029-03-14T04:00:02.947Z info  [server         ] State changed: init
2029-03-14T04:00:03.093Z debug [server         ] Compiler loaded
2029-03-14T04:00:04.003Z info  [server         ] State changed: compile-start
2029-03-14T04:00:04.495Z info  [server         ] State changed: compile-end
2029-03-14T04:00:05.066Z debug [server         ] Compiler process shutdown
2029-03-14T04:00:05.307Z debug [compiler-exec  ] Finished
2029-03-14T04:00:05.952Z debug [event-stream   ] Finished event stream
2029-03-14T04:00:06.859Z debug [compiler-exec  ] Shutting down process
2029-03-14T04:00:07.720Z info  [server         ] Closing down server
2029-03-14T04:00:08.179Z debug [server         ] Server close event
2029-03-14T04:00:08.588Z info  [server         ] Closed down server
2029-03-14T04:00:09.493Z debug [server         ] Finished processing events
2029-03-14T04:00:10.395Z debug [compiler-exec  ] 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:

• Compiler Server - Provides a simple HTTP interface to watching compiler file and state changes, and synchronizing multiple processes
• Build Compiler - Leverages Typescript to build files needed to execute compiler
• Build Manifest - Produces the manifest for the given execution
• Build Transformers - Leverages Typescript to compile all transformers defined in the manifest
• Produce Manifest Delta - Compare the output file system with the manifest to determine what needs to be compiled
• Clear all output if needed - When the compiler source or transformers change, invalidate the entire output
• Persist Manifest(s) - Ensure the manifest is available for the compiler to leverage. Multiple will be written if in a monorepo
• Invoke Compiler - Run Typescript compiler with the aforementioned enhancements