Setup

After going through this guide, you'll have a local environment set up for developing custom apps for your project.

Please note, that the words "app" and "module" are used interchangeably in this guide.

Before setting up your local development environment, you need to have a project created in the Studio. If you don't have a project yet, you can create one in the cockpit.

Prerequisites

You need to have the following tools installed before setting up your local development environment:

• Node.js >=22.12
• pnpm
• Laioutr CLI

Setup

After creating a project in the Studio, you need to set up your local development environment. Then you can start creating your new Laioutr App by cloning the Nuxt module template:

npx giget@latest gh:laioutr/app-starter
cd laioutr-app-starter

You do not have to use the template, but it will give you a good starting point.

Before installing the dependencies, you need to copy or rename the .npmrc.config file to .npmrc and replace NPM_LAIOUTR_TOKEN with the NPM token you can find in your project settings in the cockpit. If you do not do this, you will get errors like ERR_PNPM_FETCH_403 GET [...].

Now you can install the dependencies and fetch the project rc file:

pnpm install

# Fetch the laioutrrc.json file from the cockpit
laioutr project fetch-rc -p <project> -s <projectSecret>

• Replace <project> with your project name. It is in the format <organization slug>/<project slug>.
• Replace <projectSecret> with your project secret. You can find it in the project settings in the cockpit as well.

Playgrounds

Now you can start developing your app. The App Starter provides two playgrounds for you to start developing your app:

• playground/: A playground for developing UI components using your laioutrrc.json file.
• orchestr-playground/: A development environment for your orchestr integrations.

To start the playgrounds, run either of the following commands:

pnpm dev
pnpm orchestr-dev

UI Playground

Running pnpm dev will start the regular playground. This can be used together with a laioutrrc.json file to connect to an actual project in the cockpit and test the implementation of your app.

Connecting to a project in the cockpit will allow you to test with actual data from the project.

To connect, you need to open the studio-page of the project you used to run the npx @laioutr/cli project fetch-rc command. Then, press ⌘+K or Ctrl+K to open the command palette and run the command Developer: Use Localhost. This will reload the studio and connect to your localhost app.

Note: When adding new sections or blocks in this project, you currently need to restart the playground and reload the studio to see the changes. When changing fields in existing sections or blocks, you need open up the command palette and run the command Developer: Reload Client Context or refresh the page. This will be fixed in a future version.

Development

Having a look through the existing source-code, you'll notice that there is no secret sauce to creating your own app.

The most important difference between a regular Nuxt module and a Laioutr app is the addition of the registerLaioutrApp call in the module.ts file. You can use this to register laioutr-specific functionality from your app.

Adding ui sections and blocks

To add a ui section or block, you need to have the following in your module.ts file:

await registerLaioutrApp({
  /** ... */
  sections: [resolve('runtime/app/sections')],
  blocks: [resolve('runtime/app/blocks')],
});

This will search and register all section- and block-vue files in the runtime/app/section and runtime/app/block folders.

Each section and block will need to have a definition export. This is used to register the section or block with the frontend-core and the Studio.

Adding orchestr integrations

Orchestr integrations are a key part of the Laioutr ecosystem. They allow you to extend the functionality of your app with external services.

To add an orchestr integration, you need to have the following in your module.ts file:

await registerLaioutrApp({
  /** ... */
  orchestrDirs: [resolve('runtime/server/orchestr')],
});

This will automatically watch the orchestr folder for changes and restart the server if a file is changed.