@amilochau/core-vue3

@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 { CoreOptions } from '@amilochau/core-vue3':

export const environmentOptionsBuilder: (context: { host: string, subdomain: string }) => EnvironmentOptions = ({ host, subdomain }) => {
  return {
    variables: {
      VITE_API_URL: 'YOUR API BASE URI',
    },
    isProduction: !host.includes('localhost') && !subdomain.includes('dev'),
  };
};

export const coreOptionsBuilder: (context: EnvironmentOptions) => CoreOptions = ({ variables }) => ({
  application: {
    name: 'YOU APPLICATION NAME',
    contact: 'YOUR APPLICATION OWNER',
    navigation: {
      items: ref([
        // YOUR APPLICATION NAVIGATION LINKS
      ])
    },
  },
  api: {
    buildApiBaseUri: ({ relativeBaseUri }) => `${variables['VITE_API_URL']}${relativeBaseUri}`,
  },
  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 { coreOptionsBuilder, environmentOptionsBuilder } from './data/config';

import 'vuetify/styles';

export const coreVue3App = createCoreVue3App(environmentOptionsBuilder, coreOptionsBuilder);

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

import { createCoreVue3AuthApp } from '@amilochau/core-vue3-auth';
import { coreOptionsBuilder, environmentOptionsBuilder } from './data/config';

import 'vuetify/styles';

export const coreVue3App = createCoreVue3AuthApp(environmentOptionsBuilder, coreOptionsBuilder);

---

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)
useAppOptions	Lets you get the environment and 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

Application options must be configured on the application initialization - using the createCoreVue3App or the createCoreVue3AuthApp method, and can then be injected via the useAppOptions composition API.

Here are the proposed options.

Property	Usage	Type	Description
coreOptions	const { coreOptions } = useAppOptions();	CoreOptions	Core options, containing settings provided on application initialization.
environmentOptions	const { environmentOptions } = useAppOptions();	EnvironmentOptions	Environment options, containing environment variables.
apiEnabled	const { apiEnabled } = useAppOptions();	boolean	Whether API capabilities are properly configured, and can be used in the application.
authenticationEnabled	const { authenticationEnabled } = useAppOptions();	boolean	Whether identity capabilities are properly configured, and can be used in the application.

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.