# LibraryLoader

Libraryloader is a utilities library designed to allow for easy loading and 
rerouting of modules. There are three main functions to the library loader.

1. **Aliased Source Loading**: Foremostly the libraryloader allows for loading 
source files via an alias (e.g. "@Common" for loading files from a common project).
2. **Client Module Loading**: The libraryloader allows for the client to load 
it's installed node_modules in the browser.
3. **Dev node_module Loading**: Finally, the libraryloader also allows for the 
server and the client to load node_modules files from a registered local directory instead of node_modules.

> **WARNINGS**: 
> 
> LibraryLoader is designed to work with ESM modules. 
> It will not work with bundled files or other loading strategies.
> 
> LibraryLoader for the client **requires** Express.js on the server.
> 
> LibraryLoader **must** be the first import in your file, and subsequent
> imports in that file must be made with the `import()` function instead
> of the keyword, to force them to load afterwards (or they will execute 
> out of order).

## Installation:

	npm install @bikky/libraryloader

## Usage:

A complete example of how to use the libraryloader is shown below:

```typescript
//This must be the first import in the file:
import { InitialiseServer, InitialiseClient } from "@bikky/libraryloader";

InitialiseServer({
	serverPaths: {
		"@Alias": "../Alias",
	},
	node_modules: {
		server: ["./", "../Main"],
		localMode: false
	},
	logging: "silent"
});

//Other includes and code.

InitialiseClient({
    clientPaths: {
        "@Alias": "../Alias",
    },
    node_modules: {
        client: "./",
        localMode: false
    },
    logging: "silent"
}, expressApp);
```

LibraryLoader expects for the ExpressApp to be provided for the client's 
aliases, node_module access or node_module overrides to work.

### Aliased Source Loading

The following code will enable the `@Alias` alias to be used to load files 
from the `../Alias` directory on both the server and the client (path is 
relative to the server's current working directory).

You only need to supply expressApp and clientPaths if you want the aliases 
to be usable on the client.

```typescript
InitialiseServer({
    serverPaths: {
        "@Alias": "../Alias",
    },
    logging: "silent"
});

InitialiseClient({
    clientPaths: {
        "@Alias": "../Alias",
    },
    logging: "silent"
}, expressApp);
```

> Remember to import the `/@bikky/libraryloader.js` script on the client (instructions below).

### Client Module Loading

This code allows the client to load installed node_modules. It need the path
from the server's current working directory to the directory containing the
client's package.json. This is because all loaded node_modules are compared
against the client's package.json to ensure that users aren't getting access
to arbitrary scripts.

```typescript
InitialiseClient({
    node_modules: {
        client: "./"
    },
    logging: "silent"
}, expressApp);
```

> Remember to import the `/@bikky/libraryloader.js` script on the client (instructions below).

### Dev node_module Loading

This next code allows the server and the client to load node_modules from a
registered local directory instead of the node_modules folder. This is useful
for developing node_modules as it allows for easy switching between source
files and the published library.

```typescript
InitialiseServer({
    node_modules: {
        client: "./",
        localMode: true
    },
    logging: "silent"
});

InitialiseClient({
    node_modules: {
        client: "./",
        localMode: true
    },
    logging: "silent"
}, expressApp);
```

You can use the binary code to register your source directories:

	npx @bikky/libraryloader --registerSource

And if you want to unregister them later:

	npx @bikky/libraryloader --unregisterSource

## Client Setup:

The LibraryLoader must also be included on the client for it to function. If 
the LibraryLoader is correctly configured with the express app on the server,
then you can include the following script tag in the head of your html file:


On the client import the libraryloader in the <head> like so:
```html
<!-- the following script tag should be the first script tag in any .html file. -->
<script type="text/javascript" src="/@bikky/libraryloader.js"></script>
```