@amilochau/core-vue3 is a opinionated package used to create vue.js v3 applications.

Main features

• Application layout, with header and footer bars, navigation drawer, snackbar for messages
• Privacy with cookies approbation via a dedicated layer, privacy page, data cleaning on logout
• API integration, with error codes handling
• Default pages for error codes
• Reactive SEO tags per page
• Internationalization, light/dark themes
• Forms validation helpers
• Identity integration with AWS Cognito, using amilochau/core-vue3-auth
• PWA native support, with update button

Usage

amilochau/core-vue3 is proposed as a vue plugin.

1. Install the npm packages

Run the following command to install the npm package:

npm install @amilochau/core-vue3 @amilochau/core-vue3-auth

Note that amilochau/core-vue3-auth is optional - you can skip it if you don't need authentication with AWS Cognito.

2. Configure the plugin

Define your coreOptions - use a dedicated file for better code separation:

import type { MilochauCoreOptions } from "@amilochau/core-vue3"

export const coreOptions: MilochauCoreOptions = {
  application: {
    name: 'YOU APPLICATION NAME',
    contact: 'YOUR APPLICATION OWNER',
    navigation: {
      items: ref([
        // YOUR APPLICATION NAVIGATION LINKS
      ])
    },
    isProduction: true,
  },
  api: {
    gatewayUri: 'YOUR API BASE URI'
  },
  i18: {
    messages: {
      en: {}, // <== USE THIS SECTION TO ADD GLOBAL ENGLISH TRANSLATIONS
      fr: {}  // <== USE THIS SECTION TO ADD GLOBAL FRENCH TRANSLATIONS
    },
  },
  identity: {
    cognito: {
      userPoolId: 'YOUR COGNITO USER POOL ID',
      clientId: 'YOUR COGNITO CLIENT ID',
    }
  },
  routes: [], // <== USE THIS SECTION TO ADD ROUTES
  clean: () => () => {} // WHAT TO CALL TO CLEAN LOCAL DATA ON LOGOUT
}

3. Register the plugin

Register amilochau/core-vue3 in your main file:

import { createCoreVue3App } from '@amilochau/core-vue3'
import { coreOptions } from './data/config'

import 'vuetify/styles'

export const coreVue3App = await createCoreVue3App(App, coreOptions);

If you want to use authentication, register amilochau/core-vue3-auth in your main file:

import { createCoreVue3AuthApp } from '@amilochau/core-vue3-auth'
import { coreOptions } from './data/config'

import 'vuetify/styles'

export const coreVue3App = await createCoreVue3AuthApp(coreOptions);

Dependencies

The following plugins are installed by @amilochau/core-vue3:

• pinia
• vue-i18n
• vue-router
• vuetify
• vite-plugin-pwa

The following plugin is installed by @amilochau/core-vue3-auth:

• aws-amplify

See the full list of dependencies here.

Composition API

Here are the helpers you can use from your code.

| Helper | Description | | ------ | ----------- | | useApiAnonymous | Sends HTTP requests to the API gateway configured via api.gatewayUri ; manages HTTP errors | | useApi | Sends authenticated HTTP requests to the API gateway configured via api.gatewayUri ; manages HTTP errors (only if amilochau/core-vue3-auth is configured) | | useClean | Cleans data from storage, typically on logout, as configured via clean | | useCognito | Interact with AWS Cognito (only if amilochau/core-vue3-auth is configured) | | useCoreOptions | Lets you get the core options defined on plugin registration | | useHandle | Handle asynchronous requests to manage errors, with loader bar and snackbar messages | | useNavigation | Helps you use router with back navigation | | useNotifications | Lets you register your application for push notifications | | usePage | Define page metadata | | useValidationRules | Lets you use pre-defined validation rules on plain data |

Here are the pinia stores you can use from your code.

| Store name | Helper | Description | | ---------- | ------ | ----------- | | app | useAppStore | Lets you display messages in a snackbar | | cookies | useCookiesStore | Lets you known if the current user has accepted cookies | | identity | useIdentityStore | Lets you display data from the current user | | language | useLanguageStore | Lets you know the current language configured for the UI | | notifications | useNotificationsStore | Lets you get data on notifications registration | | theme | useThemeStore | Lets you know the current theme configured for the UI | | pwa | usePwaStore | Lets you manage the PWA application updates |

Options

Here are the options you should provide in the MilochauCoreOptions class.

| Configuration path | Description | | ------------------ | ----------- | | application.name | Name of the application | | application.contact | Application owner, as used in the policy page | | application.logoUrl | URL of the application logo | | application.navigation.items | Navigation links, as vuetify list items, used in the navigation drawer | | application.isProduction | Whether the current application is production | | api.gatewayUri | Base URI used by the useApi composition API | | i18n | Options used by vue-i18n | | identity.cognito | Cognito settings for authentication | | rootComponent | A custom component to use as a base parent for all the others | | routes | List of vue-router routes, to register application pages | | clean | Function called on logout, typically used to delete personal data from pinia stores | | pwa.hideInstallBtn | Hide the PWA install button from the header bar | | notifications.pushKey | Public VAPID key for push notifications | | notifications.register | Function called on notifications registration, typically used to call an API to save the registration data |

See the full definition of options here.

You can find a sample of these configuration options in the sample app options.

Notes

• You have to define a route named Home, so that default redirections can work.

Contribute

Feel free to push your code if you agree with publishing under the MIT license.