@ou-imdt/create/boilerplate/README.md

Command line tool to create team boilerplate.

# Create templates (boilerplates) documentation

Create templates (Vanilla/Vue) are comprehensive starter templates aimed at simplifying the development, build, and deployment processes for widgets. It offers developers a streamlined, modern, and efficient development experience.

## Key features

- Using [Vite](https://vitejs.dev/) which utilizes a development server powered by native ES modules, offering lightning-fast reloads. 
- Includes latest IMDT CSS and Utils, VLEAPI stub and auto resize iframe script.
- Team gitignore and gitattributes templates.
- JavaScript and CSS minification.
- Includes linting using [ESLint](https://eslint.org/).
- Supports [PostCSS](https://postcss.org/).


> Compatibility note: Requires [Node.js LTS version](https://nodejs.org/en/download/). 

## Installation

Install globally with npm:

```sh
npm install @ou-imdt/create -g
```
Or use npx for a one-off installation (always installs the latest version):

```sh
npx @ou-imdt/create
```
 
For more detailed usage instructions, refer to the [create documentation](https://bitbucket.org/lts-imd/create/src/main/readme.md). 

## Usage guide

Execute the following commands from the project's root directory:

| Command           | Action                                       |
| :---------------- | :------------------------------------------- |
| `npm install`     | Installs project dependencies                |
| `npm start`       | Starts local dev server at `localhost:3000`  |
| `npm run build`   | Build your production site to `./dist/`      |
| `npm run preview` | Preview your build locally, before deploying |

> Note: The final build is zipped and copied to the `release` folder as part of the zip NPM script in package.json, which is executed after every production build. 

## Additional dependencies

To install extra packages:

1. Search for the package on npmjs.com, ensuring it's trustworthy.

2. Run `npm install <package name>` in the root directory.

3. Import the package in your JavaScript file:

```js
import '<package name>'
```

## Handling static assets

### Importing asset as URL

When you import a static asset, it will return the resolved public URL when served:

```js
import imgUrl from './img.png'
document.getElementById('bg-img').src = imgUrl
```

For example, during development, `imgUrl` will be `/img.png` , and in the production build, it will become `/assets/img.2d8efhg.png` .

- `url()` references in CSS are handled the same way.

- Common image, media, and font file types are automatically detected as assets. You can extend the internal list using the [`assetsInclude` option](https://vitejs.dev//config/shared-options.html#assetsinclude).

### The PUBLIC directory

If you have assets that are:

- Never referenced in source code (e.g. `favicon.svg`)
- Must retain the exact same file name (without hashing)
- You simply don't want to have to import an asset first just to get its URL. (e.g. VLEAPI stub)

Then you can place the asset in a special `public` directory under your project's root. Assets in this directory will be served at root path `/` during development. And copied to the root of the dist directory as-is during production.

The directory defaults to `<root>/public`, but can be configured via the [`publicDir` option](https://vitejs.dev/config/shared-options.html#publicdir).

##### Note on `public` assets:

- You should always reference `public` assets using root absolute path - for example, `public/icon.png` should be referenced in source code as `/icon.png`.
- Assets in `public` cannot be imported from JavaScript.

### Further notes for PUBLIC/ASSETS folders

#### Using `/public/` and `/src/assets/` In Vite applications

##### Public folder:

Files placed in the `/public/` folder in the folder structure will be available, un-edited, at the root of the application after the build step.

![Public folder screenshot](./public-folder.png)


This folder is ideal for:
- Images
- Videos
- Binary files

Any plain-text files placed in here will not be minified, including JavaScript files.

###### VLEAPI

As the `vleapi.1.js` file needs to be detected by the VLE, it must be placed in the public folder to avoid modification.

###### _testData folder

The only exception to this is the `_testData` folder, which is intentionally removed at build time. This is to emulate the presence of media files in a production environment.

###### Accessing the Public folder

Files in the public folder can be accessed with a single `/`. For example, img1.png in the public folder could be accessed with `/img1.png`
 
##### Assets Folder

Files in the `/src/assets` folder will be minified at build time. JavaScript and stylesheets are usually consolidated into bundled `.js` and `.css` files to improve network requests.

This folder is ideal for:
- Plain-text code files
- Fonts
- Serialised data such as JSON intended for production.

Variables will be obfuscated, and comments will be removed at build time.

###### Accessing the Assets folder

Files in the assets folder can be accessed with `@/assets/`. For example, helper.js in the assets folder could be accessed with `@/assets/helper.js`. After building, this code will belong to a generated JavaScript file with a hard to predict name.

![Assets folder screenshot](./assets-folder.png)

## Font Awesome usage

- The team has a professional license for the latest version, providing access to all icons.
- Use icons consistently from the **Regular+Classic** sets.
- Installation guide:  [font-awesome-icons](https://bitbucket.org/lts-imd/font-awesome-icons/src/main/README.md).
  
### JSON

JSON files can be directly imported - named imports are also supported:

```js
// import the entire object
import json from './data.json'
// import a root field as named exports - helps with tree-shaking!
import { field } from './data.json'
```

## Browser support

Supports the latest stable releases of major browsers.

## Offline support (SISE)

If you need support for SISE (Students in Secure Environments), there is a vite plugin you can use [vite-plugin-singlefile](https://www.npmjs.com/package/vite-plugin-singlefile). To use the plugin, it needs to be added to the devDependencies of the project and included in the plugins array in the `vite.config.js` config file. 

```sh
npm i vite-plugin-singlefile --save-dev
```
Then update vite.config.js file by adding these in the config:

```js
//import plugin
import { viteSingleFile } from "vite-plugin-singlefile"
//add plugin to plugins array
plugins: [ viteSingleFile()]

```

## CSS pre-processors

Built-in support for .scss, .sass, .less, .styl, and .stylus files. Install the corresponding pre-processor:

```sh
# .scss and .sass 

npm add -D sass  

# .less

npm add -D less  

# .styl and .stylus 

npm add -D stylus

```

### .gitkeep file

Used to track empty directories in Git. Remove when the directory is no longer empty.

### Limitations

No `file://` protocol support: Bundled files must be run from a server due to security policies.

## Contributors

Edwin Langley, Mustafa Bektik.