Getting started

Serverless Laravel - Getting started

This guide helps you run Laravel applications on AWS Lambda using Bref. These instructions are kept up to date to target the latest Laravel version.


A demo application is available on GitHub at (opens in a new tab).


First, follow the Setup guide to create an AWS account and install the necessary tools.

Next, in an existing Laravel project, install Bref and the Laravel-Bref package (opens in a new tab).

composer require bref/bref bref/laravel-bridge --update-with-dependencies

Then let's create a serverless.yml configuration file:

php artisan vendor:publish --tag=serverless-config

How it works

By default, the Laravel-Bref package will automatically configure Laravel to work on AWS Lambda.

If you are curious, the package will automatically:


We do not want to deploy "dev" caches that were generated on our machine (because paths will be different on AWS Lambda). Let's clear them before deploying:

php artisan config:clear

When running in AWS Lambda, the Laravel application will automatically cache its configuration when booting. You don't need to run php artisan config:cache before deploying.

Let's deploy now:

serverless deploy

When finished, the deploy command will show the URL of the application.

Deploying for production

At the moment, we deployed our local codebase to Lambda. When deploying for production, we probably don't want to deploy:

  • development dependencies,
  • our local .env file,
  • or any other dev artifact.

Follow the deployment guide for more details about deploying in general.

Specifically for Laravel, Bref will automatically cache the configuration on "cold starts". This means that you don't need to run php artisan config:cache before deploying. However, if you want to improve the cold start time you can pre-generate the config cache before deploying:

php artisan config:clear && php artisan config:cache

Laravel will hardcode absolute paths in the cached configuration. To deploy a valid cached configuration, you should run the commands above in Docker, with the application mounted in /var/task (the same path as on AWS Lambda).


In case your application is showing a blank page after being deployed, have a look at the logs.

Website assets

Have a look at the Website guide to learn how to deploy a website with assets.

Laravel Artisan

As you may have noticed, we define a function named "artisan" in serverless.yml. That function is using the Console runtime, which lets us run Laravel Artisan on AWS Lambda.

For example, to execute an artisan command on Lambda, run the command below:

serverless bref:cli --args="<artisan command and options>"

For example:

serverless bref:cli --args="route:list"

For more details follow the "Console" guide.


Laravel with Inertia runs without issue, like any other website. Follow the Websites guide to learn how to deploy a Laravel with assets with Bref.