Skip to content

Template Setup and Deployment

Themes are self-contained packages that can be developed independently and deployed through the administration UI. Theme files do not belong in lara-app/resources/views.

Theme Directory

Use a short folder name containing only letters, numbers, hyphens, and underscores.

my-theme/
├── config/
│   ├── settings.json          ← Required metadata and options
│   └── values.json            ← Optional default values
├── layout/
│   └── layout.blade.php       ← Main storefront layout
├── template/
│   └── index.blade.php        ← Homepage template
├── partial/                   ← Reusable Blade partials
├── public/                    ← CSS, JavaScript, images, and fonts
└── README.md                  ← Optional theme information

Start from the maintained Bootstrap theme when you need a complete set of storefront templates:

cp -a bootstrap my-theme

After copying, update the theme metadata before making a release.

Configure Theme Metadata

The first entry in config/settings.json must be the meta section:

[
  {
    "name": "meta",
    "theme_name": "my-theme",
    "package": "com.example.my-theme",
    "version": "1.0.0",
    "screenshot": "images/preview.jpg"
  }
]

The metadata fields used during installation are:

Field Release rule
theme_name Must exactly match the top-level theme folder name.
package Use a unique identifier and keep it unchanged across all releases of the theme.
version Increase it for every release. An update must have a higher version than the installed release.
screenshot Path relative to public/, such as images/preview.jpg.

Use a predictable version sequence:

  • 1.0.0 — initial release
  • 1.0.1 — backward-compatible fix
  • 1.1.0 — backward-compatible feature
  • 2.0.0 — breaking or major redesign

For example, change version from 1.0.0 to 1.0.1 before packaging a fix. Uploading the same or a lower version over an installed theme is rejected.

See Theme Configuration for the complete settings format.

Prepare Browser Assets

Place files that must be served to browsers inside public/:

my-theme/public/
├── css/style.css
├── js/app.js
├── images/preview.jpg
└── fonts/

Reference those files from Blade with theme_asset() rather than hard-coded server paths:

<link rel="stylesheet" href="{{ theme_asset('css/style.css') }}">
<script src="{{ theme_asset('js/app.js') }}"></script>
<img src="{{ theme_asset('images/logo.svg') }}" alt="Store logo">

The platform publishes these assets to the appropriate storage or CDN location during installation.

Build the Deployment ZIP

The ZIP must contain one top-level directory whose name matches meta.theme_name. Zip the theme folder itself, not only the files inside it:

my-theme-1.0.0.zip
└── my-theme/
    ├── config/
    │   ├── settings.json
    │   └── values.json
    ├── layout/
    ├── template/
    ├── partial/
    ├── public/
    └── README.md

Run the ZIP command from the directory containing the theme folder:

zip -r my-theme-1.0.0.zip my-theme

The archive filename may include the version, but the directory inside it must remain my-theme.

Before uploading, confirm that:

  • config/settings.json is valid JSON and contains a meta section.
  • The top-level directory and meta.theme_name match exactly.
  • meta.package is unchanged from previous releases.
  • meta.version is higher than the installed version when deploying an update.
  • All required Blade templates and compiled browser assets are included.
  • Browser assets are inside public/ and use theme_asset() URLs.
  • Development-only content such as .git, editor settings, caches, source maps containing private paths, and node_modules is excluded.
  • The archive contains no symbolic links or parent-directory (..) paths.

Upload Through the Administration UI

  1. Sign in to the administration panel.
  2. Open Themes.
  3. Select Upload Theme.
  4. Choose the prepared ZIP file and submit the form.
  5. Confirm that the UI reports a successful installation or update.
  6. For a newly installed, inactive theme, select Live Preview and verify it before activation.
  7. Select Activate when the theme is ready to serve storefront traffic.

When updating an existing theme, the installer uses theme_name to identify the installed theme and checks that the uploaded version is newer. Existing administrator selections in config/values.json are preserved, while defaults for new settings can be added by the release.

Updating the active theme

Uploading a newer release of the currently active theme replaces that theme immediately. Test the release before uploading it to a production site and deploy it during an appropriate release window.

Verify the Deployment

Use Live Preview for an inactive theme, then check the storefront pages the theme owns, including:

  • Homepage
  • Login and registration
  • Product list and product details
  • Cart and checkout
  • Customer account pages

Confirm that layouts render correctly, forms submit successfully, and CSS, JavaScript, images, and fonts load without browser console or network errors.

Continue with Build Your First Theme for the Blade templates, or use the Skeleton Theme for a minimal starting point.