Download the PHP package tightenco/laravel-elm without Composer

A Platform for Elm on Laravel

Tired of the paradox of choice and constant churn on the frontend?

Want a stable and opinionated platform to build on?

This package makes it seamless.

Requirements

• Laravel 12.x+
• PHP 8.4 / 8.5
• Vite

Docs

• Installation
• Creating a page

Some Elm knowledge required from here on!

Elm learning resources

• Pass values to your page
• Share values with all your pages
• Routing
• Validation errors
• Interop with Javascript
• Persistent scroll
• Progress indicators
• Debugging
  • Laravel errors
  • Devtools (Coming soon!)
• Deploying
  • Updating Assets
• Configuration
  • Hot reloading
• Testing
  • Laravel tests
• Example apps

Installation

• Ensure you have a Laravel 12+ app ready (https://laravel.com/docs)

• Add the laravel-elm package

• Install the npm package

• Configure Vite in vite.config.js:

• Install the new npm dependencies

Optional Auth Scaffolding (Tailwind)

• Run the elm:auth command, this will:
  • add all the routes & Elm pages for basic login/registration
  • add Elm::authRoutes() to your web.php
  • setup app.blade.php with the js script includes

Note: Don't forget to run php artisan migrate!

Watch your elm files just like you would everything else

Note: Elm compilation will be drastically faster than you are used to 🔥

And open your local site! (valet link && valet open) Try going to /login or /register!

General assets note!

You can add public/build to your .gitignore if you wish to avoid committing these built files!

Creating a page

this creates resources/elm/Example/Welcome.elm

Now use the Elm facade to render your Elm Page!

routes/web.php

Hello, Example!

Some Elm knowledge required from here on

Learning resources

• https://guide.elm-lang.org/

Pass values to your page

Update your Laravel route:

routes/web.php

Update your Elm page:

resources/elm/pages/Welcome.elm

• add imports for decoding to the top
• add the name field to Props (String)
• update decodeProps with the name field
• use props.name in your view function

Share values with all your pages

AppServiceProvider.php

Routing

Routing in Laravel Elm is handled completely by your Laravel routes!

However, we can use those routes in our Elm code in a built in way.

1. Add a route, for example, our Welcome page, with a name:

2. Run the elm:routes command to generate the Elm routes file

   resources/elm/laravel-elm-stuff/Routes.elm (don't edit this manually)

3. Now we can send users to this page from Elm in our update handlers:

   Send the user to /

Or even post some data to an endpoint:

POST /todos with the "description" of "add more docs"

Validation errors

The errors value is automatically passed to your Elm views, all you need to do is add it to your props to use it!

Interop with Javascript

Talk back and forth from JS & Elm resources/elm/ExamplePage.elm

Debugging

Laravel errors

Laravel errors are displayed in a modal on the frontend during development, using the same ignition error page that you are used to!

DevTools

Coming soon!

Persistent scroll

Sometimes you want an "app like" preservation of scroll positions while navigating to and from different pages.

Laravel Elm has built in support for this, by saving the viewport values into the history.

To use it you need to:

• Import the components we need

• Add a SaveScroll msg

• Add the viewports prop

• Add the decoder for the viewports prop

• Make sure we are using the saved viewport positions on mount

• Make sure we are using the saved viewport positions on update

• As well as saving the viewport positions on scroll

• Finally, use preserveScroll on our html element ("key" should be unique for multiple scroll containers)

Progress indicators

In Elm

The loading prop is automatically passed to all your Elm views, you only need to add it to your props to use it!

In Javascript

You can access the loading state in javascript via the elm-loading event

Example using nprogress to show a top progress bar:

(after 180ms, so it does not appear for fast connections)

Deploying

Updating assets

Build your assets for production using Vite:

Configuration

Hot reloading

You may want to disable hot reloading & debugging in development if your app is extremely large / complex

Configure the Laravel Elm plugin in your vite.config.js:

This disables the generation of debug code & does not start the hot reload server during npm run dev

Testing

Laravel tests

All your normal http tests function identically to how they do in a vanilla Laravel app.

But if we want to assert against the props that are sent to Elm, we can add the X-Laravel-Elm header to our tests/TestCase.php setUp method:

Now we can test everything via normal Laravel json assertion methods!

Example apps

• TodoMVC in Laravel Elm

Contributing

To get started contributing to Laravel Elm, check out the contribution guide.

Credits

• Logan Henson
• All contributors

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

View the license for this repo.