instapack

All-in-one TypeScript and Sass compiler for web applications! 📦 🚀

## Install ### Option A: Globally Machine-Wide `npm install -g instapack` > `pnpm` can also be used but not `yarn`. **Yarn 2 is incompatible with instapack due to [Plug'n'Play](https://yarnpkg.com/features/pnp) [NOT SUPPORTED by TypeScript](https://github.com/microsoft/TypeScript/issues/28289) (and Visual Studio)!** ### Option B: Locally per Project A local installation in the project is usually more desirable for pinning and synchronizing the instapack version used by the CI and the development team. 1. Ensure `package.json` exists in the project folder. (If not, run `npm init -y`) 2. Open command prompt in that folder to install instapack locally: `npm install instapack -D -E` 3. Add [npm run scripts](https://docs.npmjs.com/cli/run-script) in `package.json`: ```json { "scripts": { "init": "ipack new react", "dev": "ipack -R", "build": "ipack", } } ``` To develop using instapack, simply run the commands: ```bash npm run init npm run dev npm run build ``` ## Quick Start Guide screenshot

```bash mkdir MyWebApp cd MyWebApp ipack new empty ipack ``` Out of the box, these files will be used as the program entry points: - `client/js/index.ts` compiled to `wwwroot/js/ipack.js` - Include this file at the bottom of your HTML / before `` using ` ``` - `copy` allows copying static assets from the npm folder (`node_modules`) into the project output folder (e.g. `wwwroot`) during build. - **This is a BETA feature** inspired by [Visual Studio LibMan](https://docs.microsoft.com/en-us/aspnet/core/client-side/libman/libman-vs?view=aspnetcore-3.0). - `library` accepts a package name. The package MUST be installed in the project `package.json` and cannot be transient implicit / merely a sub-dependency of other packages. - `files` accepts a list of file names OR folder names OR glob patterns. - `destination` accepts a sub-folder path inside the project output directory. - The copy output preserves the folder structure of the origin folders up to the topmost common directory path. (For example, copying `node_modules/library/a/b/c.txt` and `node_modules/library/a/d/f.txt` will result in `wwwroot/destination/b/c.txt` and `wwwroot/destination/d/f.txt` to be created) **Example:** > Copy all files inside `node_modules/@fortawesome/fontawesome-free/webfonts` folder, except files in that folder prefixed with `fa-brands` into project output sub-folder `wwwroot/webfonts` ```json { "instapack": { "copy": [ { "library": "@fortawesome/fontawesome-free", "files": [ "webfonts", "!webfonts/fa-brands*" ], "destination": "webfonts" } ] } } ``` - `port1` can be set for declaring a static port number to be used by the Hot Reload server. If not set or is already used, the port number will be randomized. [Read more ↓](#hot-reload-development-mode) ## Babel Integration instapack supports [`.babelrc`](https://babeljs.io/docs/usage/babelrc/) in the project root folder. **Babel transformations will be applied AFTER TypeScript compilation.** ## ESLint Integration instapack 8 supports [ESLint 7 configuration](https://eslint.org/docs/user-guide/configuring), applied directly in-memory to TypeScript source code during type-check. > Source code will be linted only when it can be compiled correctly. Here is an example `.eslintrc.json` placed in the project root (next to `tsconfig.json`). eslint and [typescript-eslint](https://github.com/typescript-eslint/typescript-eslint) packages are required to be installed in the project: ```bash npm install eslint typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser -D ``` ```json { "root": true, "parser": "@typescript-eslint/parser", "extends": [ "eslint:recommended", "plugin:@typescript-eslint/eslint-recommended", "plugin:@typescript-eslint/recommended" ], "parserOptions": { "ecmaVersion": 2020, "sourceType": "module" }, "env": { "browser": true, "commonjs": true } } ``` > To make ESLint errors visible in Visual Studio Code, install the ESLint extension: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint ### TypeScript-ESLint: Vue.js Out of the box, instapack lints `` in Vue Single-File Components without any special ESLint configuration for Vue.js! :heavy_check_mark: **However, these lint errors will not be visible in Visual Studio Code...** To remedy this issue, add these packages to the project and use the following special ESLint configuration instead: ```bash npm install eslint-plugin-vue vue-eslint-parser eslint-config-prettier -D ``` ```json { "root": true, "parser": "vue-eslint-parser", "extends": [ "eslint:recommended", "plugin:vue/recommended", "plugin:@typescript-eslint/eslint-recommended", "plugin:@typescript-eslint/recommended", "prettier/vue" ], "parserOptions": { "parser": "@typescript-eslint/parser", "ecmaVersion": 2020, "sourceType": "module" }, "env": { "browser": true, "commonjs": true } } ``` ### TypeScript-ESLint: React For React projects, add one additional package and use this `.eslintrc.json` instead: ```bash npm install eslint-plugin-react -D ``` ```json { "root": true, "parser": "@typescript-eslint/parser", "extends": [ "eslint:recommended", "plugin:react/recommended", "plugin:@typescript-eslint/eslint-recommended", "plugin:@typescript-eslint/recommended" ], "parserOptions": { "ecmaVersion": 2020, "sourceType": "module" }, "env": { "browser": true, "commonjs": true }, "settings": { "react": { "version": "detect" } } } ``` ## Hot Reload Development Mode Hot Reload development mode allows a developer to update application code while preserving runtime states, without triggering browser refresh when not needed. instapack supports Hot Reload for popular JS frameworks by using `--serve` or `-s` flags, which also enables `watch` and `dev` modes automatically. ### Vue.js Hot Reload for Vue.js projects using Single-File Component format (`.vue`) has been enabled out of the box. > No further configurations necessary! :tada: ### React When using `--experimental-react-refresh` build flag, Fast Refresh (Hot Reload) for React projects has been enabled out of the box without requiring any code changes! > If not using Fast Refresh, use [react-hot-loader](https://github.com/gaearon/react-hot-loader) package and configure the project manually, following the instructions provided. ## Module Systems ### TypeScript / ES Modules [Imports and exports](https://www.typescriptlang.org/docs/handbook/modules.html) other `.ts` / `.tsx` files in the project or normal JS modules from `node_modules`. This technique allows the ease of development using intellisense for modules with type definitions: - The module has `types` or `typings` field pointing to TypeScript declaration files (`*.d.ts`) in its `package.json`. For example: `vue`, `linq` - The module has [@types](https://microsoft.github.io/TypeSearch/) installed. For example, `react` and `@types/react` ```ts import List from 'linq'; ``` > When the imported module does not have any type definitions, it will be imported as `any` data type (no intellisense). ### ES Modules: Dynamic Import instapack supports code-splitting using ESM dynamic `import()` syntax to load on-demand modules automatically, greatly reducing the initial page load on large application: ```ts Vue.component( 'my-component', // The `import` function returns a Promise () => import('./MyComponent.vue') ) ``` An excerpt of build log when using dynamic import: ``` [02:41:10] ipack.0.js 70.1 kB [02:41:10] ipack.dll.js 220 kB [02:41:10] ipack.js 2.76 kB ``` > To use this syntax within TypeScript, `module` compiler option in `tsconfig.json` must be set to `esnext` ### CommonJS / Node.js require Imports Node.js modules within the project or from `node_modules`. However, **you WILL NOT get intellisense!** (Modules will be imported as `any` data type.) ```js const $ = require('jquery'); ``` > CommonJS `require` method in TypeScript is provided through `@types/requirejs` or `@types/node` packages. ### HTML Modules Imports an `.html` file to be minified and stringified. This technique is invaluable for working with frameworks relying on HTML-based templates such as AngularJS: ```ts // ESM syntax import template from './MyTemplate.html'; // CJS syntax const templateCJS: string = require('./MyTemplate.html'); ``` > A global TypeScript definition file for `*.html` module is required for importing the `.html` file from TypeScript using ESM syntax. ```ts // html-shim.d.ts declare module "*.html" { const _: string; export default _; } ``` ### JSON Modules Imports strongly-typed, static JSON file in the TypeScript project using the `import` syntax: ```ts // ESM syntax import settings from './settings.json'; // CJS syntax const settingsCJS = require('./settings.json'); ``` > ESM syntax requires `resolveJsonModule` compiler option in `tsconfig.json` to be set to `true` ### Vue 2: Single-File Components ```ts import Hello from './Hello.vue'; ``` ```vue ``` - A global TypeScript definition file for `*.vue` module is required for importing Vue components from TypeScript: ```ts // vue-shim.d.ts declare module "*.vue" { import Vue from "vue"; export default Vue; } ``` - Basic CSS in `

instapack

Hello from {{ compiler }} and {{ framework }}!