Next.js + Electron.js Boilerplate

[TOC]

Create apps, the morden way

Overview

Next.js is a popular framework to create web applications by using the power of React.js.

Electron.js is a popular framework to create cross-platform desktop applications.

This project is a spark between Next.js and Electron.js to leverage the power of both great frameworks to help you create cross-platform desktop applications with a breeze.

Features

Zero runtime-dependency
- Next.js will packup only neccessary codes
- No more huge node_modules
Robust dev dependencies
- All dependencies are well maintained and used by thousands of projects
- Means this boilerplate is production ready
Hot reloading during development
Secure file protocol enforced in production
Release installer/package/bundle using electron-builder
Standard js linter
Clean script help you clean generated files

Boilerplate with Material-UI

For boilerplate with material-ui, please go to material-ui branch.

Getting Started

Install nvm and node.js

Windows

Download nvm-setup.zip and install with installer, then

:: in powershell, install node latest version
nvm install latest

:: check installation
node -v

:: basic usages
nvm list
nvm use 10.12.0

Ref: nvm-windows

(Note this is a totally different project from nvm, the latter supports only Mac OS/Linux)

Mac OS/Linux

Run following in bash shell

# install nvm
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
# install node
nvm install node
# check installation
node -v
# basic usages
nvm ls
nvm use 10.12.0

Ref: nvm

Install yarn

Follow the installation guide to install yarn.

Usage

Clone/Fork Repository

git clone https://github.com/shadowwalker/next-electron
cd next-electron/src
yarn install

Understand file tree

src
├── app                    # next.js based app source folder
│   ├── components         # shared components
│   │   └── Layout.js      # layout component
│   ├── next.config.js     # next.js configuration file
│   ├── pages              # file system path based router (next.js feature)
│   │   └── index.js
│   ├── static             # static resources
│   │   └── img
│   └── utils              # utilitis
│       └── static-url.js  # used to generate path for static resources
├── main                   # used for electron
│   └── main.js            # start point for electron
├── package.json           # !change meta data to your own
├── res                    # resources used when package apps
│   └── icons
├── script
│   └── clean.js           # maintain scripts
├── test
└── yarn.lock

Develop

yarn start

This will start a next server on http://localhost:3000, and open the main window in main/main.js.

Now every change made within app folder will be rendered in the main window immediately, that's because Next.js packed with hot reloading feature for you.

Just build Next.js application as usual under app folder, it will hot reload for you.

If you need to change anything related to Electron, such as changing window size, do it in main folder and do a yarn start again.

In case you are

new to JavaScript: The Modern JavaScript Tutorial
new to Node.js: Node School
new to React.js: React Tutorial
new to Next.js: Learn Next.js
new to Electron.js: Electron API Demos
still confused: there are bunch of good materials out there waiting for you to explore

All the materials listed above is highly recommended, at least they helped me a lot to learn those things quickly and easily.

Release

yarn release-mac
yarn release-windows
yarn release-linux

This will first export app into public folder then build the packages in dist folder based on the platform you choose. Each command above should be run under their own environment.

I know it would be charming to have a yarn release to build every platform at once. But the result is not idea even it could. See

Don’t expect that you can build app for all platforms on one platform

Basically, if you don't have a windows machine (or VM), don't assume the package built on mac would have proper behaviour on a customer windows enviroment. You always want to test it on windows before shipping out.

Clean

yarn clean

Bonus

Add .gitignore

Use add-gitnore to generate .gitignore file, which use gitignore.io web service

npx add-gitignore

Atom ignored names

Append following to Atom Settings -> Ignored Names for better searching

node_modules, .next, _next

Avoid using global jsx for style

<style global jsx>{`
    body {
        margin: 0;
        overflow: hidden;
    }
`}</style>

This global style jsx should be rarely used, I found this will cause inconsistent behaviour in hot reloading.

Reference

The Modern JavaScript Tutorial

License

MIT

Thanks

This project is inspired by the following works

Building Electron Apps with Next.js

App icons borrowed from

electron/electron-api-demos

shadowwalker / next-electron