Configuring a Site for Use with Modular

Originally designed with application development in mind, Modular is also adept at supporting the construction of websites that require a Custom CMS (Content Management System) or feature restricted areas for customers, etc. This versatility makes it a robust solution for a wide range of web development needs.

TIP

It's crucial to understand two main conceptual distinctions between a Modular application (the backoffice, CMS of the site) and the Modular public site:

1. The backoffice utilizes Inertia.js to serve Vue Pages, while the public site relies on traditional Laravel routing to deliver standard Blade views. You can easily integrate Vue Components into the public site as needed (Image Carousels, Modals, Animated Charts, Interactive Maps, etc).

2. For styling Vue Pages/Components, the backoffice employs Tailwind CSS. In contrast, the public site offers the flexibility to select any CSS strategy. Options include using plain CSS, continuing with Tailwind CSS, or opting for frameworks like Bootstrap.

3. For each module in your site, the public routes are specifically defined within the modules/{moduleName}/routes/site.php file. This organizational structure allows you to manage the routing for each module separately, promoting an organized and maintainable approach to route definitions. Similarly, the restricted routes for the Backoffice are defined within the modules/{moduleName}/routes/app.php file, ensuring a clear separation between public and administrative functionalities.

To set up a site environment with Modular, follow the steps outlined below.

Preparing for the Site Installation

Before proceeding with the site installation, ensure that you have completed the steps outlined in the Modular Getting Started Guide.

Step 1 - Run the Site Installer

Starting from the root directory of your project, run the following command in your terminal. This will initiate the site installation process:

php artisan modular:publish-site-files

Step 2 - Change the default route

By default, the root route / is mapped to the Login page. If you wish to alter this, for example, by mapping the default login page to /admin and assigning the root route / to the public site, you can achieve this by modifying the Modular configuration file.

The modular:publish-site-files command, as mentioned in Step 1, publishes the Modular configuration file to your project's config/modular.php directory.

To make this change:

1. Open the config/modular.php file.
2. Update the login-url key's value from / to your desired path for the default login route.

The updated configuration should look like this:

<?php

return [
    'login-url' => '/admin',
    'default-logged-route' => 'dashboard.index',
];

TIP

Remember, the Index Module, which is installed via the modular:publish-site-files command, already has a route path / configured. This path serves as the default route for the public site in the Index Module.

Step 3 - Add the Index Service Provider

To integrate the Index Module into your site/application, you need to add the IndexServiceProvider to your app. Follow these steps for the integration:

1. Open the bootstrap/providers.php file in your project.
2. Add the IndexServiceProvider to the providers array as shown below:

return [
  ...
  Modules\Index\IndexServiceProvider::class,
];

Step 4 - Configure Vite

To configure Vite for your site, follow these instructions:

1. Open the vite.config.js file in your project.
2. Add entries for your site's files as indicated in the example below:

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import vue from '@vitejs/plugin-vue'

import Components from 'unplugin-vue-components/vite'
import AppComponentsResolver from './resources/js/Resolvers/AppComponentsResolver.js'

export default defineConfig({
  plugins: [
    laravel({
      input: [
        'resources/js/app.js',
        'resources-site/js/index-app.js',
        'resources-site/css/site.css'
      ],
      refresh: [
        'resources/**/*',
        'resources-site/**/*',
        'modules/**/views/**/*.blade.php'
      ]
    }),
    vue({
      template: {
        transformAssetUrls: {
          base: null,
          includeAbsolute: false
        }
      }
    }),
    Components({
      resolvers: [AppComponentsResolver]
    })
  ],
  resolve: {
    alias: {
      '@resources': '/resources',
      '@resourcesSite': '/resources-site'
    }
  }
})

Step 5 - Choose a CSS Alternative

Modular employs Tailwind CSS for Backoffice Components, including the CMS and Customer's Restricted Area. However, when it comes to styling the public site, the choice of CSS strategy is entirely yours. Your options are varied, encompassing everything from plain CSS to Tailwind CSS, Bootstrap, and beyond.

This documentation will include examples demonstrating how to configure your site using either Tailwind CSS (recommended as the default option) or Bootstrap.

Using Tailwind CSS

To opt for Tailwind CSS, you'll need to modify the tailwind.config.cjs file located in your project's root directory. Follow these steps:

1. Open the tailwind.config.cjs file.
2. Update the file to include your site's CSS files, as highlighted in the example below:

module.exports = {
  ...
  content: [
    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
    './storage/framework/views/*.php',
    './resources/views/**/*.blade.php',
    './resources/js/**/*.vue',
    './resources-site/views/**/*.blade.php',
    './resources-site/js/**/*.vue',
    './modules/**/views/**/*.blade.php'
  ],
  ...
}

Now that you've configured Tailwind CSS, you can begin using it to style your site, using npm run dev to compile your CSS and npm run build to compile and minify your CSS for production.

After running the npm run dev command, accessing your APP_URL in the browser, will display a Simple Page like this:

Your restrict Dashboard is still available at the /admin path, as configured in your ./config/modular.php file, under the login-url configuration key. The public site is available at the / (root) path, defined in the modules/Index/routes/site.php file.

Using Bootstrap 5

To incorporate Bootstrap 5 into your project, you must first install Bootstrap along with its required dependencies. Follow these steps:

Step 1 - Install Bootstrap 5

npm i --save bootstrap @popperjs/core
npm i --save-dev sass

Step 2 - Directories and Files Adjustments

To properly set up your project for Bootstrap 5, some adjustments to the directories and files are necessary:

1. Rename the directory from resources-site/css to resources-site/scss. This change reflects the shift from using .css files to .scss files.
2. Change the file name resources-site/scss/site.css to resources-site/scss/site.scss, updating the file extension from .css to .scss.
3. Open the newly renamed resources-site/scss/site.scss file.
4. Replace its current content with the following:

@import 'bootstrap/scss/bootstrap';

Step 3 - Update Vite Configuration

To ensure Vite correctly handles your site's styles with Bootstrap 5, you need to update the vite.config.js file:

1. Open the vite.config.js file in your project.
2. Modify the entry that imports your site's CSS file. Change it to point to the newly renamed site.scss file, as shown in the example below:

...
export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/js/app.js',
                'resources-site/js/index-app.js',
                'resources-site/scss/site.scss'
            ],
            refresh: [
                'resources/**/*',
                'resources-site/**/*',
                'modules/**/views/**/*.blade.php'
            ]
        }),
        ...
    ],
    ...
})

Step 4 - Update the Site Template

To ensure the site template uses the correct SCSS file, follow these steps:

1. Open the resources-site/views/site-layout.blade.php file in your project.
2. In the head section of this file, update the code to import the site.scss file. This can be done as shown in the example below:

<head>
  ...
  @vite(['resources-site/scss/site.scss'])
</head>

Now that you've configured Bootstrap 5, you can begin using it to style your site, using npm run dev to compile your CSS and npm run build to compile and minify your CSS for production.

TIP

To incorporate Bootstrap 5's JavaScript modules into your project, refer to the Official Bootstrap 5 documentation. This resource provides detailed instructions and examples on how to effectively utilize Bootstrap's JavaScript functionalities within your project.