Here are the list of breaking changes when upgrading between instapack major (or minor) versions.
-
Language services update:
-
TypeScript updated to 4.2.3
-
Sass updated to 1.32.8
-
-
New default template shall be
react
-
Vue 3 template is now set as
vue
-
The older Vue 2 template is now set as
vue2
-
Templates are now shipping with Bootstrap 5 beta!
-
-
Drop Node.js 10 support. (Should still work regardless)
-
TypeScript updated to 4.1.2!
- Read breaking changes here: https://devblogs.microsoft.com/typescript/announcing-typescript-4-1/#breaking-changes
-
CSS compiler services major semver bump:
-
instapack now add the required versions of
vue-loader
,vue-template-compiler
and@vue/compiler-sfc
packages to the project when detected the presence ofvue
package in the project. -
TypeScript is now version 4!
- Read breaking changes here: https://devblogs.microsoft.com/typescript/announcing-typescript-4-0/#breaking-changes
-
instapack now supports ESLint 7 + TypeScript-ESLint 3!
-
Migration guide: https://eslint.org/docs/user-guide/migrating-to-7.0.0
-
Migration guide when using instapack templates:
-
Run to update dependencies:
npm install eslint typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser -D
-
Add
"root": true,
to.eslintrc.json
-
-
-
Hot Reload now outputs to real file system.
-
Production build now cleans the JS output folder.
-
Build flag
--hot
/-h
is changed to--serve
/-s
to reduce confusion with--help
-
Build flag
--nodebug
is changed to--no-sourcemaps
-
Global instapack user settings
silent
is changed tomute
to correctly reflect the actual behavior. -
Dropped the community-deprecated TSLint in favor of ESLint-TypeScript integrations. palantir/tslint#4534
-
Dropped the (already-obsoleted)
.vue.html
module compilation.- Developers using this feature should migrate to
.vue
Single-File Component instead.
- Developers using this feature should migrate to
-
Dropped the End-of-Life (01-2020) Node.js version 8!
-
Automatic Node.js Polyfills Removed (webpack 5)
-
.mjs
and.wasm
are no longer resolved by default due to webpack 5 disabling them by default (Requiringexperiments.mjs: true
andexperiments: { asyncWebAssembly: true, importAsync: true }
https://github.com/webpack/changelog-v5#experiments) -
JS Build: Plain
.css
files will no longer be build, only<style>
code blocks in.vue
files. -
JS Build: Dependencies syntax level checking and transpilation will only be enabled for ES5 build target.
-
Production bundle will now use hidden source maps.
- Developers using Google Chrome can still load the separated source map file by right-clicking the JS source code viewer in the Debugger and selecting "Add source map..."
-
The default package manager is now set to
npm
due to uncertainty surrounding Yarn 2 Plug'n'Play not supported by TypeScript (and Visual Studio)!- instapack will force-use package manager which lock file is found first. Priority:
pnpm
>npm
>yarn
- instapack will force-use package manager which lock file is found first. Priority:
-
port2
option is no longer being used and is obsoleted. -
JS build: Exclude
/node_modules/
path from TypeScript, Vue, HTML and CSS loaders.-
Explanation: Protect projects against bundling UNCOMPILED (non-JS) libraries source code!
-
Example 1: Imagine someone wrote a
.vue
library in CoffeeScript + Less CSS, shipped it to npm, and expects consumers to compile the thing themselves. instapack will fail to compile that library despite supporting.vue
file. -
Example 2: Imagine someone wrote a
.ts
library, shipped it to npm, and expects only TypeScript users to import it as-is. He'd be right, except COMPILE ERROR! That library only can be compiled with a specific version of TypeScript2
and failed to be compiled with the latest TypeScript3
used by instapack for some reason. -
Example 3: Imagine someone shipped an unbundled JS library which automatically applies CSS when run. However, that library source code imports plain CSS files AND depends on YOUR specific webpack configuration to do the job...
-
What to do when you encounter a library like this?
-
Use other library which actually ships normal JS on npm.
-
Fork it /
git submodule
it. Transpile and bundle the library to proper ES5 yourself.
-
-
-
Sass language compiler service has been swapped to the primary Dart implementation!
- Aligned CSS
@import
syntax to the official specification: certain import queries (for example, paths ending with.css
) will be treated as ordinary CSS import.
- Aligned CSS
-
Removed
clean
command andconcat
build tools.- Legacy
angularjs
project template is now shipped with a simple concat tool (concat.cmd
), which can be adopted by projects requiring similar approach for side-loading IIFE JS.
- Legacy
-
Disable source map flag
--xdebug
or-x
has been replaced with--nodebug
or-b
-
Automatic resolution for
.html
modules is now disabled, for improved source code clarity. (You will need to explicitly write the extension when importing the file!)
- Importing
.vue.html
module is deprecated in favor of.vue
Single-File Components (which supports Hot Reload Development Mode) and will be removed in future versions!
-
TypeScript 3.0.1 notable breaking changes:
-
resolveJsonModule
regression: only works in when targeting AMDmodule
(fixed in TypeScript 3.1 / instapack 7.0.0)
-
Flag for disabling source map was changed from
-u
(uncharted
) to-x
(xdebug
). -
Sass can no longer
@import
_partial.scss files fromnode_modules
implicitly. (Behavior re-implemented in instapack 6.5.0)
- Node API now requires project folder path (root) as constructor parameter.
Modules imported from node_modules
will now be split automatically to [jsOut].dll.js
, for example: ipack.dll.js
-
This file must be included using
<script>
tag BEFORE the main app fileipack.js
-
Build speed should be improved, hopefully. (Trying to keep entry chunk size small...)
HTML template compilation mode in package.json
(string
vs vue
) has been removed in favor of special extension .vue.html
to:
-
Allow a project to have both stringified HTML and pre-compiled Vue.js HTML.
-
Simplify instapack, to make it more beginner-friendly by reducing the number of obscure options and templates...
In light of the final version of AngularJS 1.7 LTS, it is recommended for newer projects to use Vue.js / React / Inferno instead.
-
Therefore,
angular-material
template has been removed andangular-bootstrap
template has been renamed toangularjs
-
jQuery has been re-added into
angularjs
template to improve compatibility with legacy browsers, especially with Bootstrap 3.
Unfortunately, the enterprise world is not ready for JavaScript running natively in ES2015 and beyond...
The no-longer-maintained UglifyES has been dropped in exchange for the hopefully-more-stable UglifyJS 3. This change imposes stricter build requirements:
-
Only
es5
buildtarget
(set intsconfig.json
) is currently supported. Setting ES2015+ as build target WILL cause build error! -
Attempting to import a non-TypeScript ES2015+ module will fail the build! This downgrade guards the project against ninja browser incompatibilities.
-
Our supported Node.js runtime is now the latest version 8 LTS.
-
Node.js 8.3.0 and above ships with Ignition + Turbofan execution pipeline which boost overall compiler performance and shrink memory footprints!
-
Internally, we've moved from Browserify to the more modern webpack module bundler.
-
-
We have a new recommended
tsconfig.json
. Type:ipack new tsconfig
in your project root folder (where thepackage.json
andtsconfig.json
is located) to upgrade!-
It uses a standardized
ES2015
module code generation instead ofCommonJS
-
It allows Synthetic Default Imports syntax for importing non-ES modules just like a default-exported ES modules!
-
-
We've changed the CSS input file entry point from
site.scss
toindex.scss
. Please rename the said file! -
We've changed the default JS and CSS output file names to
ipack.js
(frombundle.js
) andipack.css
(fromsite.css
).-
Make sure to update your
<script src="...">
and<link href="..." />
references in the HTML files! -
If that action is prohibitive, simply use the new
jsOut
andcssOut
options to emit output file names identical to instapack 4:
-
{
"instapack": {
"jsOut": "bundle.js",
"cssOut": "site.css",
}
}