Next-electron NPM

next-electron provides the setup for building Electron apps with NextJs.

About

next-electron is a projen project that provides configuration for building Electron apps with NextJs. This project provides the following as part of the default configuration:

Configuration for hot-reloading of the Electron process and NextJs process
Full features of NextJs including /api/* routes, SSR, and static generation.
Electron-Forge integration, with setup for macOS, Windows 32-bit, and Windows 64-bit builds + installer.
Optional default template support for Chakra-UI
Zero-effort updates for future features/configuration.

Mentioned above, this project is a projen project. For those unfamiliar, this project can be setup with a simple create command. After this create command, any future configuration updates/features/setup can be brought into your project with a single update command. This gives the benefits of a project template and zero-effort updates for future features – however if this is not your cup of tea you can opt out of the projen features and simply use this project as a template to get started!

Quick Start

Note: The install will be a single command setup like the following, but is not currently configured yet: npx projen new --from next-electron. Please follow the instructions below to setup with additional steps in the meantime.

To get started, execute the following command in a new folder:

npm init -y && npm i next-electron

Next, create a file called .projenrc.js and paste the following into your file:

const { NextElectronProject, TemplateType } = require("next-electron");

const project = new NextElectronProject({
  name: "my-new-next-electron-project",
  defaultReleaseBranch: "main",
  // Don't want the Chakra setup? Try supplying TemplateType.Default
  // before running `npx projen`. If `npx projen` has already been run
  // once, see:
  // https://github.com/SpencerDuball/next-electron#change-template
  template: { type: TemplateType.Chakra },
  deps: [],
  devDeps: [],
});

project.synth();

Finally, execute the following command and your environment will be set up. Note that this command may take up a few minutes the first time it is exeucted as the npm packages will need to be installed.

npx projen

Lastly, confirm your project has been setup successfully. Run the following command get started developing!

npm run full:dev

Scripts

To get going quickly, there are a few main scripts you will need to use.

Development

To run your app in development mode:

npm run full:dev

Your app will be started with hot reloading, note that if you edit any of the files in the main/ folder, your app window will quit and reopen quickly. This is the hot reloading of the Electron process in action. If you edit any of your nextjs files, the window will not need to quit to hot reload.

Because this is a Projen project, there are a few new patterns for installing dependeinces and interacting with generated files. Please see the Working with Projen below for more info.

Production

To run a production version of your app:

# first build your app
npm run full:build

# then run your app in production
npm run full:start

Your build app files be output into two directories:

.next - This will hold all of your NextJs output files.
dist - This will hold all of your Electron output files (for the main electron process).

Packaging

To create applications and installers for your apps run the following commands:

# build for MacOS
npm run make:mac

# build for Windows 32-bit
npm run make:win32

# build for Windows 64-bit
npm run make:win64

Note that you can only build for MacOS when on MacOS.

Projen

Projen is a project that aims to extract the tedious setup & configuration from the hands of developers. For more information about projen, please see this video where creater Elad Ben-Israel gives us an introduction to the project: CDK Day 2020 - Projen

Working with Projen

Because the goal of Projen is to extract the configuration from developers, tools are available to make this as easy as possible for consumers of the project to adopt. For instance, you may have noticed that some files created in your project such as pages/api/ready-to-show.ts are not editable (you can edit in buffer, but if you try to save in your editor you will not have permission).

By design there are files that should not be edited, this includes most configuration files and files that affect the operation of the app such as pages/api/ready-to-show.ts. There are other files that are generated that are ment to be edited or even deleted, try to edit the pages/index.tsx file. Some files like this are provided as a sample and intended for the developer to edit.

So what if I really need to edit a configuration file in my project, do I have to opt out of all the features of a Projen project? Nope, you are able to edit these files, but need to specify this in your .projenrc.js file. See the section below for more details.

Editing `.projenrc.js`

Your .projenrc.js file contains all of the information used to generate the files, dependencies, dev dependencies, etc. It is outside of the scope of this project to explain all of the details about how to work with Projen, so we will refer you to the Projen project if you would like to edit your configuration: Projen

To install dependencies or devDependencies, we will supply the deps or devDeps options of your .projenrc.js project. For example:

const { NextElectronProject, TemplateType } = require("next-electron");

const project = new NextElectronProject({
  name: "wadap",
  defaultReleaseBranch: "main",
  template: { type: TemplateType.Default },
  deps: ["axios"]
  devDeps: ["storybook"],
});

project.synth();

We will show a few simple examples below as editing some aspects of your configuration will be necessary:

Editing `package.json`

Lets say you need to add additional fields to your package.json file, such as an author field:

const { NextElectronProject, TemplateType } = require("next-electron");

const project = new NextElectronProject({
  name: "wadap",
  defaultReleaseBranch: "main",
  template: { type: TemplateType.Default },
  deps: [],
  devDeps: [],
});

// Here we will add new fields to our package.json
project.addFields({
  author: "Slim Jim",
});

project.synth();

Overwriting Existing Files

If you need to overwrite existing files, Projen provides an excape hatch for making any possbile edit you could need. This is to simply overwrite the file:

const { NextElectronProject, TemplateType } = require("next-electron");

const project = new NextElectronProject({
  name: "wadap",
  defaultReleaseBranch: "main",
  template: { type: TemplateType.Default },
  deps: [],
  devDeps: [],
});

// Overwrite the `pages/api/ready-to-show.ts` file
new TextFile(this, join("pages", "api", "ready-to-show.ts"), {
  lines: ["First line", "second line"],
});

project.synth();

Adding new Configuration

There is nothing stopping you from adding additional files to your project, if there is some configuration that is left out you can add it at any time. Note that when updating your project configuration running npx projen upgrade these files may be overwritten if they are specified in the updated next-electron configruation.

Switching Templates

One feature of Projen is that we can specify sample files or sample folders to be created upon synthesis. When you run npx projen, your project is being synthesized. When sample folders such as pages/, or public/ are created they will only be created upon the first synthesis or if the sample folders/files no longer exist. To switch the template you are working with, you will need to delete the folders and files you wish to be updated and re-run npx projen. As an example, switch the quick start .projenrc.js template to default:

If you are unsure which files will need to be recreated when switching your template, the safest bet is to delete all contents of your project and restart following the quick-start instructions.

const { NextElectronProject, TemplateType } = require("next-electron");

const project = new NextElectronProject({
  name: "wadap",
  defaultReleaseBranch: "main",
  template: { type: TemplateType.Default }, // Changed the template here
  deps: [],
  devDeps: [],
});

project.synth();

Now delete the existing pages/ and public/ folders and re-run npx projen. Observe that the folders have been recreated with new sample files.