vincesoftware-apps-spykar v1.0.11

Plantagen Campaign

This repository houses the Plantagen Campaign application, designed for seamless integration with the vince-live-ui project using the Nuxt.js module system. This dynamic loading allows for efficient dependency management and modular architecture.

When deployed, the Plantagen Campaign app will be published to npm, making it easy to incorporate it into the vince-live-ui project at the desired version. This approach ensures flexibility and straightforward version control for smooth updates and maintenance.

Key Features

• Designed for dynamic loading as a dependency in vince-live-ui
• Utilizes Nuxt.js modules for efficient integration
• Streamlined version control and updates through npm publishing

This app is available in Vince Live as campaign.

Developing

Follow the below steps to develop / run the campaign app locally.

Folder structure

You need to clone the vince-live-ui repository and keep it adjacent to the app folder. So the folder structure would look like:

- My root folder
  - vince-live-ui
  - vincesoftware-apps-plantagen-campaign
  - my-cool-app2

Folder structure within the app

The recommended folder structure to be followed in the app:

- src
  - assets
  - components
  - layouts
  - pages
  - plugins
  - store
- main.js
- package.json

App execution entry point

For your app to be loaded correctly, you need to follow the below steps:

1. Ensure that the Main file in the package json is configured

package.json

{
  "name": "@vincesoftware/apps-plantagen-campaign",
  "version": "0.1.32",
  "main": "main.js", // important to give this entry point
  ---
  ---
}

2. Ensure that you have configured the app metadata in package json file.

package.json

{
  "name": "@vincesoftware/apps-plantagen-campaign",
  "version": "0.1.32",
  "main": "main.js",
  "vinceLiveApp": { // important to give this key
    "name": "campaign", // depends on what app are you building, ex price-and-discounts
    "basePath": "apps" // must be same
  }
}

3. Defining nuxt module in main.js

main.js

import {
    defineNuxtModule,
    extendPages,
    addPlugin,
    addLayout
} from '@nuxt/kit';
import * as appRoutes from './routes.json'; // created by `npm run build-routes`
import * as packageJson from './package.json';

export default defineNuxtModule({
    meta: packageJson,
    async setup(options, nuxt) {
        extendPages((pages) => {
            // Add /test page
            appRoutes.default.forEach((r) => {
                pages.push(r);
            });
        });
    },
});

As you can see the file called routes.json is imported to provide the page info. You can generate the routes using the helper script which can be simply copied from .build folder (you can copy entire .build folder). Refer Generate routes

Configuring the campaign app in Vince Live application.

Once the campaign app is cloned we need to configure the vince-live-ui folder to load the module from local instead of from npm.

1. Goto vince-live-ui/nuxt.config.js and scroll to modules section where you can define the nuxt module dependency.
2. Copy the full folder path of the campaign app and paste it as an entry to the modules array.
3. Comment / disable the dependency of the campaign app provided via npm.

Example:

...
...
** Nuxt.js modules
  */
    modules: [
        'bootstrap-vue/nuxt',
        '@nuxtjs/style-resources',
        '@nuxtjs/pwa',
        // '@vincesoftware/apps-plantagen-campaign' -- comment this one
        'F:\\Vince\\UI\\vincesoftware-apps-plantagen-campaign'
    ],
...
...

Generating routes in campaign app

We need to generate the routes for each pages that we have defined in the app, we have a helper script for the same we can use the same. Note that all pages must be present within a folder called pages.

Run the below script in the app folder.

npm run build-route

Running locally

The app can be only started and executed in Vince Live application, so to run and debug the app we need to follow the below steps:

1. Goto vince-live-ui
2. Run npm run dev
3. Edit your code in the app repository, any changed files will automatically update the VL UI web page

Advanced

• Extending layouts
• Extending VUEX store
• Extending CSS
• Extending plugins

Extending layouts

Apps can also have an ability to define their own layouts and as a nuxt module, it is supported with minimal config. To create and configure a new layout in the app, first we need to create a new .vue file in src/layouts folder. And it has to be configured in main.js while we are defining a nuxt module. To define a new layout we can use addLayout method.

Example:

import { addLayout } from '@nuxt/kit';
export default defineNuxtModule({
    meta: packageJson,
    async setup(options, nuxt) {
        ...
        ...
        addLayout(
            {
                src: path.resolve(__dirname, source + '/layouts/CampaignLayout.vue'),
                filename: 'CampaignLayout.vue',
            },
            'CampaignLayout'
        );
        ...
        ...
    },
});

Components within layout files:

NOTE: Any component reference in a layout file will fail to resolve, so to fix this issue we can register the component globally so we do NOT need to import them separately, we can directly use them.

To define a new component, you can use vue.component() method in a plugin.

Example:

register-component-plugin.js

import { VueInstance } from '@/store/index';
import Navigation from '../components/SideNavigation.vue';
export default () => {
    VueInstance.component('CampaignNavigation', Navigation);
};

NOTE: A layout name in Nuxt module must be used with kebab-case

Example:

<template>...</template>
export default {
    components: {
    },
    layout: 'campaign-layout', // use as kebab-case
    data () {..}

Extending VUEX Store

To extend / add a new VUEX store, you can directly open the plugin called register-store which you can find inside src/plugins folder and simply import the store from the folder and use a method called registerModule.

Example:

import campaignStore from '../store/index';
const packageJson = require('../../package.json');

export default ({ app, store }) => {
    store.registerModule(`${packageJson.vinceLiveApp.basePath}/${packageJson.vinceLiveApp.name}`, campaignStore);
};

The basePath and the name of the app will be defined in package.json, to ensure that no conflicting stores are registerd with same name / path. So this guideline MUST be followed.

Extending CSS

You can also extend the CSS support for the app by maintaining separately in the app code base. To do so, simply define them in main.js.

Example:

export default defineNuxtModule({
    meta: packageJson,
    async setup(options, nuxt) {
        ...
        ...
        nuxt.options.css.push(
            path.resolve(__dirname, source + '/assets/styles/main.scss')
        );
    },
});

Extending plugins

Plugins can be extended as well in main.js while we define the nuxt module.

Example:

import { addPlugin } from '@nuxt/kit';
export default defineNuxtModule({
    meta: packageJson,
    async setup(options, nuxt) {
        addPlugin(path.resolve(__dirname, source + "/plugins/register-store.js"));
    },
});

Deployment process

Change log

Versioning

npm module versioning follows a standardized format called Semantic Versioning (SemVer). Each version number consists of three parts: major.minor.patch.

Major, Minor, and Patch

• Major: Indicates breaking changes. When you make significant changes to your code that are not backward-compatible, you should increment the major version.
• Minor: Represents non-breaking, backward-compatible changes, such as the addition of new features or improvements. Increment the minor version when you add functionality that doesn't break existing code.
• Patch: Refers to bug fixes and small changes that don't affect the overall functionality. Increment the patch version when you make bug fixes or minor tweaks that don't change the API or add new features.

Example

Consider a version number: 1.3.7

• The major version is 1, meaning that there have been breaking changes since the initial release.
• The minor version is 3, indicating that three non-breaking feature updates have been introduced.
• The patch version is 7, representing that seven bug fixes or small changes have been made.

When updating your repo, ensure you follow the SemVer principles to maintain consistency and help others understand the significance of each version release.