fix(vite-plugin): optionally resolve alias, add preliminary doc (#1731)

docs/user-docs/TOC.md

@@ -105,6 +105,7 @@
     * [AUR0013](developer-guides/error-messages/0001-to-0015/aur0013.md)
     * [AUR0014](developer-guides/error-messages/0001-to-0015/aur0014.md)
     * [AUR0015](developer-guides/error-messages/0001-to-0015/aur0015.md)
+* [Bundlers](developer-guides/bundlers/README.md)
 * [Recipes](developer-guides/scenarios/README.md)
   * [CSS-in-JS with Emotion](developer-guides/scenarios/css-in-js-with-emotion.md)
   * [TailwindCSS integration](developer-guides/scenarios/tailwindcss-integration.md)

docs/user-docs/developer-guides/bundlers/README.md

@@ -6,3 +6,66 @@ description: >-
 ## Webpack
 
 ## Vite
+
+### Installing
+
+For the latest stable version:
+
+```bash
+npm i -D @aurelia/vite-plugin
+```
+
+For our nightly builds:
+
+```bash
+npm i -D @aurelia/vite-plugin
+```
+
+### Usage
+
+In `vite.config.js`:
+
+```js
+import { defineConfig } from 'vite';
+import aurelia from '@aurelia/vite-plugin';
+
+export default defineConfig({
+  ...,
+  plugins: [aurelia()],
+});
+```
+
+For apps in TypeScript, an extra typing definition is required for html module. You can add following file to your typing folder.
+
+Note that this is generated by default by the aurelia cli.
+
+`html.d.ts`
+```ts
+declare module '*.html' {
+  import { IContainer } from '@aurelia/kernel';
+  import { BindableDefinition } from '@aurelia/runtime';
+  export const name: string;
+  export const template: string;
+  export default template;
+  export const dependencies: string[];
+  export const containerless: boolean | undefined;
+  export const bindables: Record<string, BindableDefinition>;
+  export const shadowOptions: { mode: 'open' | 'closed'} | undefined;
+  export function register(container: IContainer);
+}
+```
+
+#### Dev config
+
+By default, the aurelia vite plugin generates aliases to dev packages for better experience during development. It'll detect development mode based on the `mode` config from `vite`. You can also override using `useDev` options, in case there needs to be clarity into some behavior of the applications:
+
+```ts
+import { defineConfig } from 'vite';
+import aurelia from '@aurelia/vite-plugin';
+
+export default defineConfig({
+  ...,
+  plugins: [aurelia({ useDev: true })], // always use dev bundles
+});
+```
+```

packages-tooling/vite-plugin/src/index.ts

@@ -48,8 +48,10 @@ export default function au(options: {
         'router-lite',
       ].reduce((aliases, pkg) => {
         const name = pkg === 'aurelia' ? pkg : `@aurelia/${pkg}`;
-        const packageLocation = require.resolve(name);
-        aliases[name] = resolve(packageLocation, `../../esm/index.dev.mjs`);
+        try {
+          const packageLocation = require.resolve(name);
+          aliases[name] = resolve(packageLocation, `../../esm/index.dev.mjs`);
+        } catch {/* needs not to do anything */}
         return aliases;
       }, ((config.resolve ??= {}).alias ??= {}) as Record<string, string>);
     },