Help with applications

[treagod]

Hi!

For context, I've worked a lot with RoR in the past. Therefore the project/application structure is new to me. To understand it better I had a look how Django is handling this. They also have a good tutorial about apps. The whole concept looks quite nice to organize stuff.

What I'm missing in Martens documentation is a how to work with apps. The documentation states that there are apps and how they are generated/structured, but now how to integrate them (beside adding them to installed_apps). I've had a look at the plugins (auth, session-db, etc...) how it works, looks quite simple. For my usecase I don't want to initialize a complete repository to organize my apps.

So I created a website

marten new project mysite

Installed dependencies

cd mysite/ && shards install

Create an application in my project

marten new app blog --dir=src/blog

Added it to my project:

# Create src/blog/models/article.cr
# Add `require "./blog/**"` to  "src/project.cr"
# Add `BlogApp` to `config/base.cr`

Generated migrations

marten genmigration

which returned

Generating migrations for app 'blog':
  › Creating [src/blog/migrations/202308030836021_create_blog_article_table.cr]... DONE
      ○ Create blog_article table

And tried to migrate them, which resulted in

In src/blog/migrations/202308030836021_create_blog_article_table.cr:3:43

 3 | class Migration::Blog::V202308030836021 < Marten::Migration
                                               ^----------------
Error: undefined constant Marten::Migration

Do you have some guidance what I'm doing wrong?

[ellmetha]

Hey! 👋

Thanks for the feedback! Yes the Marten applications mechanism is definitely inspired by Django's. 🙂
There is some documentation around applications and how to create them but I guess it's not visible enough or complete enough. I'll definitely look into that.

Regarding the error you are encountering, I think there may be two reasons:

1. The requirement of ./blog/**" in src/project.cr should be changed to ./blog/app. The reason behind that is that CLI-related abstractions related (such as the migration ones, which are only used through the Marten CLI) are not required by Marten itself when you require Marten via require "marten". The automatically generated blog/app.cr file requires only the abstractions that are intended to be used when your project is running (eg. models, handlers, etc).
2. Related to the first point, you need to add another requirement to your project in order to ensure that the migrations of the blog app are available when running marten migrate. Indeed, a blog/cli.cr file was generated for the blog application, and it is intended to be required in the src/cli.cr file (require "./blog/cli").

This should fix the issue you were encountering!

The src/project.cr file really contains the requirements of your application while the src/cli.cr file contains requirements related to the use of the Marten CLI. This allows to avoid slowing the compilation of your project by having to process CLI-related abstractions that are not needed for your server to run.

Finally, this mechanism is by no means perfect and it's on my todo list of things to improve in the framework. Ideally, we would benefit from having a generation command that is capable of adding a new application to the project automatically by creating the application files, but also adding it the list of installed applications, adding the associated requirements, etc. The new app command can be a starting point presently, but it is more intended to be used to create standalone applications that live outside of an existing project (eg. third-party apps that have their own associated repository).

Also happy to review PRs with ideas on how to make this behavior clearer or to discuss alternative ideas!

[treagod]

Thanks! That worked.

I'll think about how the generation of apps can be made better. For now it should suffice to extend the documentation to show how to bring the apps and project together, both as a shard and as a direct component.