web.compiler

A precompiler to run, compile and update (multi-layered) web projects.

Language	Compiles	Info
java	✓	Known Issues
typescript	✓	Known Issues
twirl	✓	Known Issues
svelte	✓	Known Issues
sbt	✖	Known Issues
scala	✖	Known Issues

Requirements

1. Current version of SBT
2. Current version of watchman

Compatibility

wompiler	Node 14	Node 16	Node 18
<2.12	YES	no	no
2.12.x	YES	YES	untested
>=2.13	untested	YES	YES

Note: See Contributing for compatibility while developing.

Usage

In most modern web projects utilizing version 2+, wompiler does not need to be executed manually. Projects integrating the web.compiler.plugin SBT Plugin will start wompiler automatically as part of the Play! Run-Hook.

For a full list of commands please execute the wompiler --help command.

Note For creating a distributable package, you should use sbt dist instead of wompiler dist if your project uses the web.compiler.plugin plugin.

Note about wompiler clean

This will delete the following directories or files relative to your current working directory.
Wompiler will not check whether you are located in a valid project. It also will not validate the type of file it deletes (file / directory).

Open to see the deleted directories and files

Path	Reason
./target	Generated by scala
./project/target	Generated by scala
./public/bundles	Generated by webpack
./package-lock.json	Generated by npm (using a generated package.json)
./package.json	Generated by wompiler
./settings.json	Generated by wompiler
./conf/application.conf	Generated by wompiler
./conf/routes	Generated by wompiler
./app/mirror	Generated by wompiler
./app/inclMirror	Generated by wompiler
./node_modules	Generated by npm (using a generated package.json)

Limitations

Annotations

No extends clause is permitted in Java annotation types. Therefore, they cannot be overridden in the traditional sense.
See Java Language Specification - Chapter 9.6.

Create a layered type like public @interface MyAnnotationL1 {..} anyway, because wompiler copies the members of the highest layer to the mirror. This means that if you "override" an annotation using wompiler, you have to copy the member declarations from all other layers! When you add a new member, it must have a default value so that the usages of the annotation in the code of the other layers are not broken.

Ebean Models

Ebean Model classes are handled in a different way from other java classes. The code of all layers including fields, constructors, and methods are copied to the mirror instead of the mirror class extending from the highest layer class. The reason is that ebean doesn't handle fields of parent classes. The Ebean Model compiler is limitted in the following ways:

• Generic Supertype: Nested generic supertypes are not supported
  OK: public class XyzL2 extends SuperModel<Abc>
  Bad: public class XyzL2 extends SuperModel<List<String>>
• Method and Constructor Annotations: Only repeatable or the following marker annotations are supported when the annotation is repeated on the overridden method in further layers. Using a non-marker variant of one of the following annotations or any other annotation might lead to a compiler error stating that a non-repeatable annotation was repeated in the mirror class.
  Supported annotations are: @Override, @Nonnull, @Nullable, @CheckReturnValue, @CheckForNull, @Deprecated, @Transactional
  OK: @Nonnull @Override public void test()
  Bad: @Nonnull(when = When.MAYBE) @Override public void test()
• Super Calls: Calling super(...) or super.method(...) only has a defined behaviour in the constructor or method that overrides the excact super method to call.
  OK:

  public void test() {
    super.test();
  }

  Bad:

  public void test() {
    super.doSomething();
  }

Contributing

Note: Building the project requires Node 16 or 18. Running and debugging should still work with Node 14.

If you want to contribute to the wompiler project, follow the steps below.

1. Clone the Repository
2. Run npm i to install dependencies
3. Implement your fixes or features on a separate branch
4. Test your code
5. Build the project: npm run build (requires Node 16 or 18)
6. Change directories to a web project you can test your changes with
7. Run your local wompiler with: node <PATH-TO-WOMPILER-PROJECT>\dist\cli.js <command>
   eg. node C:\Java\rb_web\web.compiler\dist\cli.js precompile
8. Commit your changes
9. Open a Pull Request on GitHub

Release

Only create a new release if your changes have been reviewed and merged into master/next.

1. Update version and automatically create git tag
   npm version (major|minor|patch) on master
   or npm version (premajor|preminor|prepatch|prerelease) --preid=rc on next
2. Push the newly created tag
   git push origin --tags