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).

| 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>

  Unsupported:

  public class XyzL2 extends SuperModel<List<String>>

• Additional Bounds in Class Type Arguments have no defined behaviour and may not be precompiled correctly.
  OK:

  public class MyClass<T extends SuperType<X>> { }

  Unsupported:

  public class MyClass<T extends SuperType<X> & Interface<UUID>> { }

• 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()

  Unsupported:

  @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();
  }

  Unsupported:

  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
   1. "Install" your changes locally by running npm link in the root folder of the wompiler project. (Only once)
   2. Build the project after each change: npm run build (requires Node 16 or 18)
   3. Change directories to a web project you can test your changes with
   4. Run wompiler using the commands you're familiar with, like wompiler precompile or any custom alias. Because you ran the link command, this now runs your development version of wompiler. *
   5. When you're done testing, use npm i -g @informaticon/web.compiler to re-install the production version of wompiler.
5. Commit your changes
6. Open a Pull Request on GitHub

* If you want to attach a debugger, you need to run node --inspect-brk <PATH-TO-WOMPILER>/dist/cli.js <command>. On Windows, an example might look like this:
node --inspect-brk %userprofile%\AppData\Roaming\npm\node_modules\@informaticon\web.compiler\dist\cli.js precompile.

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