nextron: A TypeScript repository from saltyshiomix

2024 Roadmaps - I'm back!

Support

Next.js vs Nextron

next	nextron
`v14.x`	`v9.x`
`v12.x` / `v13.x`	`v8.x`
`v11.x`	`v7.x`
`v10.x`	`v6.x`
`v9.x`	`v5.x`
`v8.x`	`v4.x`
`v7.x`	`v2.x` / `v3.x`
`v6.x`	`v1.x`

Package Manager

npm, yarn and pnpm are supported.

My Belief for Nextron

Show a way of developing desktop apps with only web knowledge
Easy to use
Be transparent and open to OSS developers

Usage

Create Application with Template

We can use examples/* as a template.

To create the examples/with-tailwindcss, run the command below:

# with npx
$ npx create-nextron-app MY_APP --example with-tailwindcss

# with yarn
$ yarn create nextron-app MY_APP --example with-tailwindcss

# with pnpm
$ pnpm dlx create-nextron-app MY_APP --example with-tailwindcss

Run Electron with Development Mode

Run npm run dev, and nextron automatically launches an electron app.

{
  "scripts": {
    "dev": "nextron"
  }
}

Production Build

Run npm run build, and nextron outputs packaged bundles under the dist folder.

{
  "scripts": {
    "build": "nextron build"
  }
}

Basic Directory Structures

.
├── main
│   ├── background.ts
│   └── preload.ts
├── renderer
│   ├── next.config.js
│   ├── pages
│   │   ├── home.tsx
│   │   └── next.tsx
│   ├── preload.d.ts
│   ├── public
│   │   └── images
│   │       └── logo.png
│   └── tsconfig.json
├── resources
│   ├── icon.icns
│   └── icon.ico
├── nextron.config.js
├── electron-builder.yml
├── package.json
├── tsconfig.json
└── README.md

`next.config.js`

// in `./renderer/next.config.js`
module.exports = {
  // we need to export static files so as Electron can handle them
  output: 'export',

  distDir:
    process.env.NODE_ENV === 'production'
      ? // we want to change `distDir` to "../app" so as nextron can build the app in production mode!
        '../app'
      : // default `distDir` value
        '.next',

  // e.g. home.html => home/index.html
  trailingSlash: true,

  // we need to disable image optimization, because it is not compatible with `{ output: 'export' }`
  images: {
    unoptimized: true,
  },

  // webpack config for next.js
  webpack: (config) => {
    return config
  },
}

`nextron` or `nextron dev` Options

`--renderer-port` (default: `8888`)

It specifies next dev server port:

{
  "scripts": {
    "dev": "nextron --renderer-port 7777"
  }
}

`--run-only` (default: `undefined`)

It suppresses hot reloading of the main process:

{
  "scripts": {
    "dev": "nextron --run-only"
  }
}

`--startup-delay` (default: `0`)

It waits until renderer process is ready (milliseconds):

{
  "scripts": {
    "dev": "nextron --startup-delay 3000"
  }
}

`--electron-options` (default: `undefined`)

We can pass electron args via --electron-options:

{
  "scripts": {
    "dev": "nextron --electron-options=\"--no-sandbox\""
  }
}

`nextron build` Options

NOTE:

To build macOS binary, your host machine must be macOS!
Please consider to use electron-builder.yml instead of these CLI options.
- Command Line Interface (CLI) - electron-builder
- Common Configuration - electron-builder

To build Windows 32 bit version, run npm run build:win32 like below:

{
  "scripts": {
    "build": "nextron build",
    "build:mac": "nextron build --mac",
    "build:mac:universal": "nextron build --mac --universal",
    "build:linux": "nextron build --linux",
    "build:win32": "nextron build --win --ia32",
    "build:win64": "nextron build --win --x64"
  }
}

`--config` (default: `./electron-builder.yml`)

{
  "scripts": {
    "build": "nextron build --config ./configs/electron-builder.prod.yml"
  }
}

`--publish` (default: `undefined`)

Note

Highly recommend to use electron-builder.yml:

https://www.electron.build/configuration/publish

`--no-pack` (default: `undefined`)

This option skips packaging by electron-builder:

{
  "scripts": {
    "build": "nextron build --no-pack"
  }
}

Build Configuration: `electron-builder.yml`

Edit electron-builder.yml for custom build configurations:

appId: com.example.nextron
productName: My Nextron App
copyright: Copyright © 2020 Yoshihide Shiono
directories:
  output: dist
  buildResources: resources
files:
  - from: .
    filter:
      - package.json
      - app
publish: null # see https://www.electron.build/configuration/publish

For more information, please check out electron-builder official configuration documents.

Custom Config: `nextron.config.js`

module.exports = {
  // specify an alternate main src directory, defaults to 'main'
  mainSrcDir: 'main',
  // specify an alternate renderer src directory, defaults to 'renderer'
  rendererSrcDir: 'renderer',

  // main process' webpack config
  webpack: (config, env) => {
    // do some stuff here
    return config
  },
}

Custom Babel Config for Main Process

We can extends the default babel config of main process by putting .babelrc in our project root like this:

.babelrc:

{
  "presets": ["nextron/babel"]
}

Examples

examples/basic-lang-javascript

# with npx
$ npx create-nextron-app my-app --example basic-lang-javascript

# with yarn
$ yarn create nextron-app my-app --example basic-lang-javascript

# with pnpm
$ pnpm dlx create-nextron-app my-app --example basic-lang-javascript

examples/basic-lang-javascript-python

# with npx
$ npx create-nextron-app my-app --example basic-lang-javascript-python

# with yarn
$ yarn create nextron-app my-app --example basic-lang-javascript-python

# with pnpm
$ pnpm dlx create-nextron-app my-app --example basic-lang-javascript-python

examples/basic-lang-typescript

# with npx
$ npx create-nextron-app my-app --example basic-lang-typescript

# with yarn
$ yarn create nextron-app my-app --example basic-lang-typescript

# with pnpm
$ pnpm dlx create-nextron-app my-app --example basic-lang-typescript

examples/basic-launch-app-from-url

This example shows how to open your app from browser URL.

Note: this example works only production build!

# with npx
$ npx create-nextron-app my-app --example basic-launch-app-from-url

# with yarn
$ yarn create nextron-app my-app --example basic-launch-app-from-url

# with pnpm
$ pnpm dlx create-nextron-app my-app --example basic-launch-app-from-url

# --------------------------------------------------------------

# Production build
$ yarn build (or `npm run build` or `pnpm run build`)

After production build, open your-custom-protocol://open?token=jwt-value in your browser, then the app will be shown like a magic!

If you want to change schema URL, please edit electron-builder.yml#protocols:

protocols:
  name: Your App Name
  schemes: [your-custom-protocol-edited]

Then, you can see the app from URL: your-custom-protocol-edited://any-uri-here?data=include-any-data.

examples/basic-store-data

# with npx
$ npx create-nextron-app my-app --example basic-store-data

# with yarn
$ yarn create nextron-app my-app --example basic-store-data

# with pnpm
$ pnpm dlx create-nextron-app my-app --example basic-store-data

examples/custom-build-options

# with npx
$ npx create-nextron-app my-app --example custom-build-options

# with yarn
$ yarn create nextron-app my-app --example custom-build-options

# with pnpm
$ pnpm dlx create-nextron-app my-app --example custom-build-options

examples/custom-renderer-port

# with npx
$ npx create-nextron-app my-app --example custom-renderer-port

# with yarn
$ yarn create nextron-app my-app --example custom-renderer-port

# with pnpm
$ pnpm dlx create-nextron-app my-app --example custom-renderer-port

examples/with-ant-design

# with npx
$ npx create-nextron-app my-app --example with-ant-design

# with yarn
$ yarn create nextron-app my-app --example with-ant-design

# with pnpm
$ pnpm dlx create-nextron-app my-app --example with-ant-design

examples/with-chakra-ui

# with npx
$ npx create-nextron-app my-app --example with-chakra-ui

# with yarn
$ yarn create nextron-app my-app --example with-chakra-ui

# with pnpm
$ pnpm dlx create-nextron-app my-app --example with-chakra-ui

examples/with-emotion

# with npx
$ npx create-nextron-app my-app --example with-emotion

# with yarn
$ yarn create nextron-app my-app --example with-emotion

# with pnpm
$ pnpm dlx create-nextron-app my-app --example with-emotion

examples/with-material-ui

# with npx
$ npx create-nextron-app my-app --example with-material-ui

# with yarn
$ yarn create nextron-app my-app --example with-material-ui

# with pnpm
$ pnpm dlx create-nextron-app my-app --example with-material-ui

examples/with-next-i18next

# with npx
$ npx create-nextron-app my-app --example with-next-i18next

# with yarn
$ yarn create nextron-app my-app --example with-next-i18next

# with pnpm
$ pnpm dlx create-nextron-app my-app --example with-next-i18next

examples/with-tailwindcss

# with npx
$ npx create-nextron-app my-app --example with-tailwindcss

# with yarn
$ yarn create nextron-app my-app --example with-tailwindcss

# with pnpm
$ pnpm dlx create-nextron-app my-app --example with-tailwindcss

Develop

Basic

$ git clone https://github.com/saltyshiomix/nextron.git
$ cd nextron
$ pnpm install
$ pnpm dev # default is examples/basic-lang-javascript

Developing `examples/*`

$ pnpm dev <EXAMPLE-FOLDER-NAME>

Developing for your own project

Install development version of nextron

$ cd nextron
$ npm install
$ npm run build
$ npm link

Install linked nextron in your project

$ cd your-project
$ npm link nextron

On every change in nextron, run npm run build in nextron folder and restart your project

Maintainers ⚡

For more information, please see Looking for maintainers ⚡ #244.

Community

You already create apps with nextron? Feel free to share your apps or services: Made by nextron? #406

create-nextron-app - Create Nextron (Next.js + Electron) apps in one command ⚡

License

This project is licensed under the terms of the MIT license.

saltyshiomix/nextron

Support

Next.js vs Nextron

Package Manager

My Belief for Nextron

Usage

Create Application with Template

Run Electron with Development Mode

Production Build

Basic Directory Structures

next.config.js

nextron or nextron dev Options

--renderer-port (default: 8888)

--run-only (default: undefined)

--startup-delay (default: 0)

--electron-options (default: undefined)

nextron build Options

--config (default: ./electron-builder.yml)

--publish (default: undefined)

--no-pack (default: undefined)

Build Configuration: electron-builder.yml

Custom Config: nextron.config.js