RFC: Pevensie v0.1.0

[isaacharrisholt]

Pevensie is the first attempt at a batteries-included web framework for the Gleam programming language. Think Laravel/Phoenix for Gleam.

This discussion is for discussing what a very basic initial version of Pevensie would look like. What modules should it include? What should the overall ethos of the framework be?

Required modules will probably look something like:

• Server
• (Routing?)
• Auth
• Sessions
• Frontend templating
• DB models (migrations?)
• Form/API request validation
• Setup/codegen CLI
• Queues/background workers
• Email
• Payments

The term 'module' here is being used to mean 'part of the Pevensie ecosystem', and not necessarily a module within a Pevensie mega package. I think each should be installable and usable separately, but they will be built to work best with each other. See this comment for more context.

These are listed roughly in priority order, though it's unclear as of yet whether a routing module is necessary. There may be a case for it for autogenerating an OpenAPI schema, though that would likely come at the cost of performance when compared to pattern matching. Ideally each module (apart from maybe the server) should be optional when building a Pevensie application, but they should all work together seamlessly.

Ideally, Pevensie should be built on the great work of the community so far. This will enable us to get started quicker and hopefully lower the barrier to entry for existing Gleam devs coming to Pevensie.

Current thoughts are:

• Build primarily on top of either Mist or Wisp
• Use Lustre to create interactive frontends

Naming: why 'Pevensie'?

Pevensie is named after one of the best Lucys in modern literature - Lucy Pevensie from Narnia! In some sense, this was inspired by Laravel, which was so named because 'Laravel' rhymes with 'Cair Paravel' (from Narnia) and Taylor Otwell thought the name was cool. Well, we decided to run with the theme, and since Gleam's mascot is already called Lucy, we didn't think there was much debate to be had.

Pevensie modules could also be Narnia themed. For example:

Module	Name	Example	Reason
Auth	Aslan	import pevensie/aslan	Aslan symbolises protection and authority in Narnia
CLI	Wardrobe	gleam run -m pevensie/wardrobe new <name>	The wardrobe is how Lucy Pevensie discovers Narnia in The Lion, The Witch and The Wardrobe

More name suggestions are welcome! Make sure you provide reasoning :)

[bcpeinhardt]

Not overly fond of the cute module names tbh 😂 it just adds overhead knowledge for onboarding and keeping track of the project structure

[isaacharrisholt]

You'd prefer pevensie/auth, for example?

[bcpeinhardt]

Yeah exactly. I wouldn’t mind them having cute names if they were separate libraries meant to be swappable but if they’re just modules I think clear names are much better.

[isaacharrisholt]

I need to make this clearer in the RFC, but from Discord:

What is the case for a whole separate Thing vs a collection of packages and a template repo using Wisp?

This is effectively a collection of packages, but they're packages that will primarily be designed to work together. For example, the Pevensie server will (probably) be an abstraction on top of Wisp or Mist (undecided whether control > not having to reimplement stuff yet), and the auth server will be a collection of utils designed to work with that, but would still probably be usable within vanila Wisp/Mist.

[naomieow]

Thought for this one, maybe a "best of both worlds"? Where the package has a cute name but you import from what it is? I'm not entirely sure how much it would impact anything.
E.g.
gleam add aslan
import pevensie/auth

[isaacharrisholt]

I'm not sure that would be a great UX, honestly

[naomieow]

A billing/payments module would be quite nice, but is definitely not top-priority.

[isaacharrisholt]

You're right! Added

[dinkelspiel]

Might be ambitious but a livewire esque experience would be a nice addition though a case might be made for lustre to implement this instead of pensive as I see no work for a modern frontend in this spec.

I also don't really understand the reasoning behind maybe including a Routing module. A web framework not including routing seems like a wierd decision if it is intended for the web.

[naomieow]

The "maybe" is sourced from a conversation had in the Discord. Routing could fairly easily be handled with pattern matching, but pattern matching doesn't allow reflection. By having a routing module, reflection on the router would be possible.

[isaacharrisholt]

Frontend stuff would probably be left primarily to Lustre. There's a case to be made for potentially wrapping parts of Lustre to reduce some of the boilerplate, but that definitely wouldn't be a priority.

As for routing, @naomieow summed it up nicely. Pattern matching would give you better performance at the cost of reflection, but a routing module would also have the cost of not being totally type safe (i.e. you'd have to bundle params into a Dict(String, String) or similar.

In Discord we discussed an API like this:

Routes([
  Route(method: GET, path: [Literal("posts"), IntParam("id")], handler: my_handler_func),
])

This would allow us to generate an OpenAPI spec, for example. We'd also be able to do runtime validation on the id path parameter, but we'd still probably have to pass this to the user as a string or a Dynamic value.

Having a routing module does potentially give us other benefits too, though. We'd be able to handle things like form validation, query parameter validation, body validation, etc.. It's probably something we'll implement at some point, but there's a good bit of discussion to be had around what it looks like and how it works.

[dinkelspiel]

Is there a plan to implement robust middleware support in this router? It's always something I miss when using many javascript frameworks.

[isaacharrisholt]

Middleware in Gleam is already pretty easy thanks to use:

fn middleware(req: Request, next: fn(Request) -> Response) -> Response {
  let req = before(req) // Before the handler
  let resp = next(req)
  after(resp) // After the handler
}

fn handler(req: Request) -> Response {
  use req <- middleware(req)

  // do work

  wisp.ok()
}

Whether there's much benefit to adding this to a router, I'm not sure.

[GV14982]

I'm not sure if this is within the scope of this project or if it should be handled elsewhere, but I would love a sort of front-end "component framework", similar to something like shadcn/ui or material ui. As a lazy front-end dev, I sometimes just want to use pre-built components for 90% of things and not have to think about it.

[braedencrankd]

Regarding the frontend, consider building an API for InertiaJS. This approach offers a tighter coupling between the server and frontend, with the added advantage of using React, Vue, or Svelte, which already provide component frameworks and state management solutions.

[isaacharrisholt]

That's not a bad idea! It probably wouldn't be a priority - we already have Lustre, and as I said, Pevensie is mostly going to focus on backend stuff - but I can see an InertiaJS package being a great future addition. I think the first step for me is going to be figuring out auth. It'll help me see how things are going to have to fit together in the long run, as it kinda touches everything.

[braedencrankd]

I agree that focusing on the frontend should not be a priority. I have yet to properly explore Lustre, and while I experimented with Elm in the past, I did not fully take to its array-style HTML syntax. It seems sensible to prioritise authentication if you are building on top of Wisp. Looking back at Laravel 3.0 on Git, the key features were:

• Simple routing using closures or controllers
• Views and templating
• Driver-based session and cache handling
• Database abstraction with a query builder
• Authentication
• Migrations
• PHPUnit integration

[isaacharrisholt]

@braedencrankd what do you mean by 'driver-based'? The ability to swap out the database used?

[braedencrankd]

This was just pulled from the Larvel 3.0 docs haha. I'm guessing it means having either redis or database session/cache drivers.

[eznix86]

You forgot about Caching, where we can have different drivers, any db; valkey (redis), sqlite, and others

[isaacharrisholt]

Yeah they seem reasonable, but there's no reason all the libs in the 'slim' pack need to be bundled together. A lot of them would work really well as standalone things

[eznix86]

(coming back from one of your videos on SSR)

Maybe you already thought about it:
lpil/html-lustre-converter can be used for the template engine it goes to a cached folder. So it doesn't regenerate it.

Example; we have an extension:
index.glaze
You can write gleam inside the html and it generates the template in a cache!

What do you think?

[lpil]

How would you compile it? How would you get good type error messages? It would be confusing if they come from the generated code.

[isaacharrisholt]

Agreed, it would be difficult. I'm also not sure it would provide much in the way of value - writing Lustre by hand isn't difficult and it's already a reasonable abstraction. People can always use the HTML converter tool if they want.

[eznix86]

Well, I was more focus onto having html + lustre mixed together a bit like how PHP does it, or any other template engine. So basically we have a lustre side and a html side, when compiled it would generate the lustre code to compile, like the template engine (example glaze) would translate everything into a lustre format which is used for the compilation.

I didn't think about the errors, but in case of the errors, since it is lustre code, it can point directly to the node which has errors.

reasonable abstraction.

I believe a reasonable abstraction is to have html + some gleam (lustre) together (example jsx which is javascript + html)

[fawaz-alesayi]

I'm working on my first project in Laravel, and one thing that's making it both easy and enjoyable is Jetstream. Jetstream includes features like multi-user schemes and other essentials commonly found in SaaS applications.

I believe that Pev (Pevensie) could benefit from having something similar. We might want to start with a simpler solution like Breeze.

[dinkelspiel]

Breeze is just a template that can be used through a cli. I am really for having a breeze like system in Pevensive but I don't think it should be anywhere near the requirements for a 1.0. Breeze was a culmination of a decade of experience in Laravel so it's not something I'd have on the roadmap yet.

[garthtrickett]

Rather than grouping by technicality (endpoints, controllers, service, repository, etc), set the framework up in a way that favours a vertical slice architecture where each of the app's endpoints is it is own file and shared code is moved into a common folder.

vs

Then rather than having to navigate through 4-5 files you've got everything in one place (maximises locality of behaviour)

[isaacharrisholt]

I've been doing some thinking about how Pevensie should be structured. Originally the plan was to have a number of separate libraries that the user could pick and choose from and plumb together. The reason for this decision was that a lot of the services we're going to be building for Pevensie don't already exist for Gleam, and there would be a community benefit to having them separate.

However, there's also a case to be made for keeping everything tightly integrated. Done well, a tightly-coupled, opinionated framework can drastically improve developer velocity and it would actually be easier to implement on our side, too.

That said, I still want Pevensie to have a wider benefit to the community, so I think that any core functionality we build should (where sensible) be released as a separate package.

A good example is Pevensie/jargon, which was originally going to be part of pevensie/auth, but makes sense to publish to Hex separately.

This would also give us tighter control over the framework as a whole. Thoughts?

[garthtrickett]

I think you can make them separate packages while still making it feel like one cohesive whole. AdonisJS is an example of this done well IMO

[lpil]

I think making things all-as-one and then extracting those smaller pieces as they come forth is a good approach

[isaacharrisholt]

Yeah I agree. It'll be easier to architect and iterate if most things aren't public-facing.

[versecafe]

Sitemap & Robot policy generation would be a huge convenience it's a pain to do right now there's no libraries for it and it's a huge part of larger projects to make sure search engines are accurately finding and ranking content.

[isaacharrisholt]

Yep! This is one that'll probably come as part of some sort of router