Play Framework Module Inconsistency

Play framework has really poor documentation about how to create modules. I recently read the suggested guide from objectify.be dated from march of 2012. The problem I have with these instructions, is the inconsistency of how it is currently being implemented in the objectify.be project; I assume this is because of the outdated instructions. Play Authenticate! is using the code/sample-app approach while other projects such as SignalJ are taking the sub-module/sub-project approach,

The most common standard I have found so far is having two projects within your git repository: A code folder where the module code lives and the sample-app which can be used to understand how to module can be implemented. The sample-app makes a reference of the module by using a sim-link and creating a reference to the code folder in your build.sbt file.

Your folder structure would look something like this

.
├── code 
│   ├── app
│   ├── build.sbt
│   ├── conf 
│   ├── ...
└── sample-app
    ├── app
    ├── build.sbt
    ├── conf
    ├── module 
    │   └── play-module-sample -> ../../code
    │   ├── ...

The build.sbt located in the sample-app looks something like this:

lazy val {{moduleName}} = project
   .in(file("modules/{{module-name}}"))
   .enablePlugins(PlayJava)

lazy val root = (project in file("."))
  .enablePlugins(PlayJava, PlayEbean)
  .settings(
    libraryDependencies ++= appDependencies
  )
  .dependsOn({{moduleName}})
  .aggregate({{moduleName}})

One of the main problems I saw with this is that the sample-app is compiling the module every time it is run and it doesn’t guarantee that the version you are testing against is the one released to the public. I guess this why Play Authenticate decided to change the sbt to depend on the maven repo instead of pointing to the sub-project inside of sample-app which is linking to  . view source.

The steps to create a module are kind of simple which are explained with more detailed in the How to create a Module with Play Framework.