kidkarolis / jetpack

🚀 Jetpack – Webpack made more convenient.

Webpack made more convenient.

Jetpack wraps webpack to create a smoother developer experience. Jetpack can be used instead of webpack, webpack-cli, webpack-dev-server and webpack-dev-middleware without writing any configuration. Jetpack is a thin wrapper around webpack, and can be extended with any webpack configuration.

• Sensible defaults to handle modern JavaScript, CSS and images.
• Preconfigured swc-loader for speedy compilation.
• Preconfigured core-js for polyfilling missing browser features.
• Preconfigured postcss-loader with postcss-preset-env including autoprefixing.
• Modern bundles by default with no async/await transpilation.
• Differential builds with modern/legacy bundles served based on user agent headers.
• CSS modules one config flag away.
• Sass auto enabled by installing node-sass.
• JSX detection with React.createElement or h depending on dependencies.
• Hot reloading using fast-refresh for React as well as for vanilla JavaScript and CSS.
• Automatic chunk splitting with inlined runtime and HTML generation.
• Single dependency with hassle-free updates.

Why use jetpack? To avoid rolling your own custom webpack config or having to paste it from old projects. Jetpack has a set of defaults that should get you off the ground quickly. And with the proxy config or the universal jetpack/serve middleware you don't have to worry about wiring up webpack dev middleware or dev server – everything just works.

Usage

Install globally or locally:

$ npm install -g jetpack

In your project with package.json or index.js, start your app on http://localhost:3030:

$ jetpack

To build the app for production to a dist directory:

$ jetpack build

Inspect the bundle size and make up:

$ jetpack inspect

Print what browsers will be supported:

$ jetpack browsers
$ jetpack browsers --coverage=GB

Use jetpack anywhere, anytime

One of jetpack goals is to help you run any piece of JavaScript in a browser as easily as it is to run node scripts. Install jetpack globally and point it to any file on your machine. This is an alternative to jsfiddle / codepen / codesandbox style of hacking on things.

$ jetpack ~/Desktop/magic.js

Or any project on your machine:

$ jetpack --dir ~/projects/manyverse

Use jetpack with a server API

Another goal of jetpack is to assist you in building complete, production apps. Very often in addition to developing the clientside application, you are also developing an API. Jetpack has a few features to make building such apps easier.

Point your package.json#main to your server entry and package.json#browser to your client entry.

Now you can run your API server together with jetpack in a single command:

$ jetpack -x

Alternatively, specify any command to execute: $ jetpack -x 'nodemon ./api'

Use this even if your server is not written in node

$ jetpack -x 'rails s'

Jetpack provides an ability to proxy requests to your api by specifying proxy configuration in jetpack.config.js or mounting the dev server to your application server using the jetpack/serve middleware. Read more about it in Workflow and deployment docs.

Documentation

• All configuration options
• Customizing Webpack
• Customizing SWC
• Customizing PostCSS
• Customizing Browserslist
• Workflow and deployment
• Differential serving
• Hot reloading
• Comparison to cra, pwa-cli, parcel, etc.

Recipes

• Adding Flow
• Adding Typescript
• Server side rendering

Motivation

This project is an exploration of some ideas accumulated over a few years using webpack in a variety of projects. Webpack is a very powerful and flexible tool. It applies to a lot of use cases and that is one of the reasons it has so many configuration options. Webpack also evolved over the years but preserved backward compatibility as much as possible to support the large ecosystem built around it.

Jetpack is an exploration of how using webpack could be made easier if the defaults, the CLI usage patterns and the configuration would be different.

jetpack's Issues

Support preload for resource

It's important to support resource preload when page is served by SSR, which makes meaningful performance for UX.

Remove "core-js" from alias

Since version 0.16 and above "core-js" set as an alias, that causes an error for libraries like AntD that uses an older version of core-js (core-js@2).

Default jetpack clean to y/N

Add comparison to "node ." to docs

Cannot run create-react-app with typescript

npx create-react-app example --typescript
cd ./example

create jetpack.config.js from doc

jetpack --verbose
jetpack › Jetpack 0.12.1 �
jetpack › Webpack 4.28.3
jetpack › Dir G:\source\example
jetpack › Entry .
jetpack › Asset server http://localhost:3030
jetpack › Failed to compile! Found 1 error:

  multi (webpack)-hot-middleware/client.js?path=/assets/__webpack_hmr&noInfo=true&reload=false .
  Module not found: Can't resolve '.' in 'G:\source\example'

Improve the chart in the README

It's not very clear and has some mistakes.

Do differential builds, modern by default

Integrate webpack-dashboard

integration with SSG?

Hi, my SPA is primarily showing/hiding/enabling/disabling bits of pre-generated html, which I'm generating with 11ty. Would jetpack be able to use my generated index.html as the template for including the bundle(s) or would I be better off just including references to them in the templates which build my index.html or do custom webpack stuff rather than jetpack?

Some options from config/CLI ignored or not copied

Some configuration options (from jetpack.config.js or CLI) don't seem to be copied into the options passed into Webpack and the rest of the tooling:

• options.css: this was where I found the issue; setting options.css.features['nesting-rules'] = true wasn't turning on that feature.
• options.browsers: also not copied/merged.
• Others: these are the 2 that currently affect me, but other options also seem to be ignored, or can only be set by one of CLI/config file not both (e.g: options.hot seems like it can only be set via CLI, not by config file). It'd be good to be consistent with what options can be set where, and any differences/exceptions noted in the docs.

The relevant part of my jetpack.config.js file looks like this:

module.exports = {
    // ...
    browsers: [
        'last 2 versions',
        'cover 99%',
        'not < 1%',
        'not dead'
    ],
    css: {
        features: {
            'nesting-rules': true
        }
    }
    // ...
};

(Other than that, really liking the tool, saved me some time and setup, and is a good reference approach to learn from!)

Take a free port if 3000 is taken

Flesh out the examples

Create `jetpack-start`

Or mini-jetpack that is used only in production, this way you can avoid installing webpack or nodemon. Hm, having said that in Docker deploys you usually build inside docker.

Pure backend: got errors "Module not found: Can't resolve..."

I have a "simple" Nodejs API, using Nestjs.
When running Jetpack, the console and the webpage generate Module not found: Can't resolve errors.

Sample error:

$ npm run start:jet

> [email protected] start:jet /home/tom/Dev/api
> jetpack ./src/main.ts

jetpack › Jetpack 0.12.1 🚀
jetpack › Webpack 4.29.0
jetpack › Dir /home/tom/Dev/api
jetpack › Entry ./src/main.ts
jetpack › Asset server http://localhost:8080
jetpack › Failed to compile! Found 1 error:

  ./node_modules/@grpc/grpc-js/build/src/channel.js
  Module not found: Can't resolve '../../package' in '/home/tom/Dev/api/node_modules/@grpc/grpc-js/build/src'

The UI at localhost:8080 shows a lot more errors of the same kind (Module not found: Error: Can't resolve 'fs' in '/home/tom/Dev/api/node_modules/glob')

jetpack.config.js (from Jetpack doc, except for entry/port/verbose).

module.exports = {
  // dir: 'src',
  entry: 'src/main.ts',
  port: 8080,
  verbose: true,
  webpack (config) {
    config.resolve.extensions = ['.tsx', '.ts', '.js']
    config.module.rules[0].oneOf.push({
      test: /\.tsx?$/,
      loader: 'ts-loader',
      exclude: /node_modules/,
    })
  }
}

tsconfig.json (default from Jetpack doc)

{
  "compilerOptions": {
    "target": "es5",
    "allowJs": true,
    "skipLibCheck": false,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react"
  },
  "include": [
    "src"
  ]
}

Project structure:

• src in src/
• entry point is src/main.ts

If you have an idea, I would be please to try it.

Thanks.

Support --inspect

Default to `preact.h` instead of `Preact.h`?

Even though react convention is to import to capitalised React, on the preact docs examples, it imports to preact rather than Preact. Maybe default to that instead to align with their docs?

Implement `jetpack/handle`

Explore integration with neutrino

Instead of maintaining custom webpack config, use neutrino's web one. Plus toggle between react/preact automatically. Plus support custom presets or extensions the way neutrino does it.

Figure out how to best deploy jetpack apps to CDN

Perhaps combine with bapistrano.

Include hash into the output file names

Proxy configuration doesn't pass query string parameters

It isn't hard to reproduce, simply create an endpoint in your back-end server that requires a query parameter, and configure jetpack like so:

proxy: {
    '/api/*': 'http://some-backend'
  },

the code in lib/proxy.js is missing req.query being passed to reqOpt.path, will do a PR if one doesn't exist.

Add favicon to the default html header

Could be nice to add something like that to the default HTML:

<link rel="icon" type="image/x-icon" href="{{assets/public/favicon.ico}}" />

Include config for async/await, it's not currently correctly building that bit

Setting hot: false in jetpack.config.js doesn't take effect

Using Jetpack API, setup an ES6 module entry for backend

Hello KidkArolis,
My backend is written with esm and I would like to have both backend and frontend coexisting. Frontend side was transparent to setup, but I am left wondering how with Jetpack, it should be done to require esm to enable ES6 modules in my backend.

Thanks for your project, it is elegant IMHO. And thanks also for your feedback.

Fix preact support

Rewrite the //# sourceMappingURL= for the runtime

Before inlining the runtime into html, rewrite the sourceMappingURL to

//# sourceMappingURL=/assets/...

Add unstrap command

Detailed diagnostic info on crash

It's the most frustrating thing when a tool such as jetpack doesn't work, in dev locally, but especially in production where it's much harder to debug.

It shouldn't be hard to print out detailed debug info upon crash, e.g.

• all the config options it managed to collect
• current working dir
• whether client side code exists in location (easy to miss the build step for a number of reasons)
• whether jetpack.config.js exists
• the version of jetpack, node and npm

Runtime source map url wrong

It starts with no / so is not relative to the base and instead incorrectly loads relative to the current url.

Errors out with SourceMaps Error

I did the following
npm i -g jetpack
created an index.js and added console.log('hello')
ran jetpack

Looks like there are similar issues in other projects: angular/angular-cli#1982
Seems to be something with symlinking node_modules? Still investigating...

Error below:

➜  jetpack-hyperapp jetpack
##################################################
#                                                #
#  App started on http://localhost:3000          #
#                                                #
##################################################
/home/john/.npm-global/lib/node_modules/jetpack/node_modules/source-map/lib/source-map-consumer.js:704
      throw new Error('"' + aSource + '" is not in the SourceMap.');
      ^

Error: "/home/john/.npm-global/lib/node_modules/jetpack/node_modules/html-entities/li
b/html5-entities.js" is not in the SourceMap.
    at BasicSourceMapConsumer.SourceMapConsumer_sourceContentFor [as sourceContentFor
] (/home/john/.npm-global/lib/node_modules/jetpack/node_modules/source-map/lib/source
-map-consumer.js:704:13)
    at /home/john/.npm-global/lib/node_modules/jetpack/node_modules/source-map/lib/so
urce-node.js:133:40
    at Array.forEach (native)
    at Function.SourceNode_fromStringWithSourceMap [as fromStringWithSourceMap] (/hom
e/john/.npm-global/lib/node_modules/jetpack/node_modules/source-map/lib/source-node.j
s:132:32)
    at SourceMapSource.node (/home/john/.npm-global/lib/node_modules/jetpack/node_mod
ules/webpack-sources/lib/SourceMapSource.js:42:20)
    at ReplaceSource.node (/home/john/.npm-global/lib/node_modules/jetpack/node_modul
es/webpack-sources/lib/ReplaceSource.js:69:29)
    at CachedSource.node (/home/john/.npm-global/lib/node_modules/jetpack/node_module
s/webpack-sources/lib/CachedSource.js:12:23)
    at /home/john/.npm-global/lib/node_modules/jetpack/node_modules/webpack-sources/l
ib/ConcatSource.js:40:49
    at Array.map (native)
    at ConcatSource.node (/home/john/.npm-global/lib/node_modules/jetpack/node_module
s/webpack-sources/lib/ConcatSource.js:39:60)
➜  jetpack-hyperapp

View webpack.config final output

It would be nice if one can see the final output of the Webpack configuration

Title option from config file is never used

The 'title' property of the config is not used at all - the title is always taken from the package.json name field, or is 'jetpack' if that does not exist.

In /lib/options.js:
title: pkg(dir).name || 'jetpack',

A better way would be:
title: options.title || pkg(dir).name || 'jetpack',

Support jetpack.config.ts

see https://webpack.js.org/configuration/configuration-languages/

Live reload doesn't work if you roll your own server

I think requests to /client/__webpack_hmr are going to the server and not making it to the client

Consider using `browser|main` as client/server entries

Pass NODE_ENV as env to the html template

Improve support for static sites

• output index.html into dist so that it could be used right away for client apps

• in the index, replace {{assets}} token appropriately

• think about multi entry use case, e.g. multiple static pages with different entries.. perhaps best left to a custom script, maybe add a hook to jetpack.config.js for building, postbuild or smth. Tbh, multi entrypoints can just be multiple jetpack apps. jetpack a, jetpack b, etc. Anything more involved, perhaps out of scope, it's rare for spas to need multiple html entrypoints. Should jetpack read jetpack.config.js from the target dir if it finds one? Probably yes, why wouldn't it.

CSS-modules: composes

Jetpack is awesome @KidkArolis !
I have created a test case for CSS-modules here, npm t should point it out.
CSS-modules seem to work, but I can't get composes to inherit properties.
No matter what I tried, I couldn't fix it, hence the issue report.

.parent {
  background-color: black;
  color: green;
}

.child {
  composes: parent;
  color: red;
}

Expected:

.child {
  background-color: black;
  color: red;
}

Actual:

.child {
  color: red;
}

Should take path as arg, e.g. `jetpack .`

Use compression and other middlewares in the default express server

If only [legacy] is configured, use jetpack's defaults for [modern]

Provide an example of how to use module/no module

By default, jetpack produces separate modern and legacy entry points, index.html and index.legacy.html. Since those files contain the runtime and embed entry points, it's not clear how one would go about module/no-module approach instead. I think this could possibly be achieved by customising the html template used. Try to see if it really works and provide an example in docs.

Core-js compatibility issue

Since version 17.0 it is no longer an option to use corejs@2
Any advice?