\n\n`@amilochau/core-vue3` is a opinionated package used to create vue.js v3 applications.\n\n## Main features\n\n- Application layout, with header and footer bars, navigation drawer, snackbar for messages\n- Privacy with cookies approbation via a dedicated layer, privacy page, data cleaning on logout\n- API integration, with error codes handling\n- Default pages for error codes\n- Reactive SEO tags per page\n- Internationalization, light/dark themes\n- Forms validation helpers\n- Identity integration with AWS Cognito, using `amilochau/core-vue3-auth`\n- PWA native support, with update button\n\n## Usage\n\n`amilochau/core-vue3` is proposed as a vue plugin.\n\n1. Install the npm packages\n\nRun the following command to install the npm package:\n\n```pwsh\nnpm install @amilochau/core-vue3 @amilochau/core-vue3-auth\n```\n\nNote that `amilochau/core-vue3-auth` is optional - you can skip it if you don't need authentication with AWS Cognito.\n\n2. Configure the plugin\n\nDefine your `coreOptions` - use a dedicated file for better code separation:\n\n```typescript\nimport type { CoreOptions } from '@amilochau/core-vue3':\n\nexport const environmentOptionsBuilder: (context: { host: string, subdomain: string }) => EnvironmentOptions = ({ host, subdomain }) => {\n return {\n variables: {\n VITE_API_URL: 'YOUR API BASE URI',\n },\n isProduction: !host.includes('localhost') && !subdomain.includes('dev'),\n };\n};\n\nexport const coreOptionsBuilder: (context: EnvironmentOptions) => CoreOptions = ({ variables }) => ({\n application: {\n name: 'YOU APPLICATION NAME',\n contact: 'YOUR APPLICATION OWNER',\n navigation: {\n items: ref([\n // YOUR APPLICATION NAVIGATION LINKS\n ])\n },\n },\n api: {\n buildApiBaseUri: ({ relativeBaseUri }) => `${variables['VITE_API_URL']}${relativeBaseUri}`,\n },\n i18: {\n messages: {\n en: {}, // <== USE THIS SECTION TO ADD GLOBAL ENGLISH TRANSLATIONS\n fr: {} // <== USE THIS SECTION TO ADD GLOBAL FRENCH TRANSLATIONS\n },\n },\n identity: {\n cognito: {\n userPoolId: 'YOUR COGNITO USER POOL ID',\n clientId: 'YOUR COGNITO CLIENT ID',\n }\n },\n routes: [], // <== USE THIS SECTION TO ADD ROUTES\n clean: () => () => {} // WHAT TO CALL TO CLEAN LOCAL DATA ON LOGOUT\n});\n```\n\n3. Register the plugin\n\nRegister `amilochau/core-vue3` in your main file:\n\n```typescript\nimport { createCoreVue3App } from '@amilochau/core-vue3';\nimport { coreOptionsBuilder, environmentOptionsBuilder } from './data/config';\n\nimport 'vuetify/styles';\n\nexport const coreVue3App = createCoreVue3App(environmentOptionsBuilder, coreOptionsBuilder);\n```\n\nIf you want to use authentication, register `amilochau/core-vue3-auth` in your main file:\n\n```typescript\nimport { createCoreVue3AuthApp } from '@amilochau/core-vue3-auth';\nimport { coreOptionsBuilder, environmentOptionsBuilder } from './data/config';\n\nimport 'vuetify/styles';\n\nexport const coreVue3App = createCoreVue3AuthApp(environmentOptionsBuilder, coreOptionsBuilder);\n```\n\n---\n\n## Dependencies\n\nThe following plugins are installed by `@amilochau/core-vue3`:\n- `pinia`\n- `vue-i18n`\n- `vue-router`\n- `vuetify`\n- `vite-plugin-pwa`\n\nThe following plugin is installed by `@amilochau/core-vue3-auth`:\n- `aws-amplify`\n\nSee the full list of dependencies [here](/packages/core-vue3/package.json).\n\n## Composition API\n\nHere are the helpers you can use from your code.\n\n| Helper | Description |\n| ------ | ----------- |\n| `useApiAnonymous` | Sends HTTP requests to the API gateway configured via `api.gatewayUri` ; manages HTTP errors |\n| `useApi` | Sends authenticated HTTP requests to the API gateway configured via `api.gatewayUri` ; manages HTTP errors *(only if `amilochau/core-vue3-auth is configured`)* |\n| `useClean` | Cleans data from storage, typically on logout, as configured via `clean` |\n| `useCognito` | Interact with AWS Cognito *(only if `amilochau/core-vue3-auth is configured`)* |\n| `useAppOptions` | Lets you get the environment and core options defined on plugin registration |\n| `useHandle` | Handle asynchronous requests to manage errors, with loader bar and snackbar messages |\n| `useNavigation` | Helps you use router with back navigation |\n| `useNotifications` | Lets you register your application for push notifications |\n| `usePage` | Define page metadata |\n| `useValidationRules` | Lets you use pre-defined validation rules on plain data |\n\nHere are the `pinia` stores you can use from your code.\n\n| Store name | Helper | Description |\n| ---------- | ------ | ----------- |\n| `app` | `useAppStore` | Lets you display messages in a snackbar |\n| `cookies` | `useCookiesStore` | Lets you known if the current user has accepted cookies |\n| `identity` | `useIdentityStore` | Lets you display data from the current user |\n| `language` | `useLanguageStore` | Lets you know the current language configured for the UI |\n| `notifications` | `useNotificationsStore` | Lets you get data on notifications registration |\n| `theme` | `useThemeStore` | Lets you know the current theme configured for the UI |\n| `pwa` | `usePwaStore` | Lets you manage the PWA application updates |\n\n## Options\n\nApplication 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.\n\nHere are the proposed options.\n\n| Property | Usage | Type | Description |\n| -------- | ----- | ---- | ----------- |\n| `coreOptions` | `const { coreOptions } = useAppOptions();` | `CoreOptions` | Core options, containing settings provided on application initialization. |\n| `environmentOptions` | `const { environmentOptions } = useAppOptions();` | `EnvironmentOptions` | Environment options, containing environment variables. |\n| `apiEnabled ` | `const { apiEnabled } = useAppOptions();` | `boolean` | Whether API capabilities are properly configured, and can be used in the application. |\n| `authenticationEnabled` | `const { authenticationEnabled } = useAppOptions();` | `boolean` | Whether identity capabilities are properly configured, and can be used in the application. |\n\nSee the full definition of options [here](/packages/core-vue3/src/types/options.ts).\n\nYou can find a sample of these configuration options in the [sample app options](/packages/playground/src/data/config.ts).\n\n## Notes\n\n- You have to define a route named `Home`, so that default redirections can work.\n\n--- \n\n## Contribute\n\nFeel free to push your code if you agree with publishing under the [MIT license](./LICENSE).\n","readmeFilename":"README.md"}
![\"License\"](\"https://img.shields.io/github/license/amilochau/core-vue3\")
\n \n \n ![\"Release\"](\"https://img.shields.io/github/v/release/amilochau/core-vue3\")
\n \n \n ![\"Version\"](\"https://img.shields.io/npm/v/@amilochau/core-vue3.svg\")
\n \n \n ![\"Downloads\"](\"https://img.shields.io/npm/dt/@amilochau/core-vue3.svg\")
\n \n