⚡️ Vite plugin for quick cross-platform application development ⚡️

Ask a Question

Table of Contents

• About
• Getting Started
  • For Electron
  • For SSR
  • For SSG
• Roadmap
• Contributing
• Support
• License

---

About

Armonia is a vite plugin for quick application development.

Almost bare metal, Armonia allows you to develop and build application across multiple target without leaving the comfort of vite.

It currently supports:

• SSR
• SSG (preview)
• Electron

Read the online documentation, explore the examples or take a look at the not so starter project.

Getting Started

In your vite project install armonia and cross-env:

$ pnpm i @armonia/vite cross-env -D

Add the armonia plugin to your vite.config.ts

// vite.config.ts
import { defineConfig } from 'vite'
import { armonia } from '@armonia/vite'

export default defineConfig({
  plugins: [armonia()]
})

For Electron

Install electron and electron-builder:

$ pnpm i electron electron-builder -D

Create the file src-electron/index.ts, it will be automatically discovered by Armonia:

// src-electron/index.ts
import { app, BrowserWindow } from 'electron'

let mainWindow: BrowserWindow | undefined

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    useContentSize: true
  })

  if (import.meta.env.DEV) {
    mainWindow.loadURL(import.meta.env.ELECTRON_APP_URL)
    mainWindow.webContents.openDevTools()
  } else {
    mainWindow.webContents.on('devtools-opened', () => {
      mainWindow.webContents.closeDevTools()
    })

    mainWindow.loadFile(import.meta.env.ELECTRON_APP_URL)
  }

  mainWindow.on('closed', () => {
    mainWindow = null
  })
}

app.whenReady().then(createWindow)

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

app.on('activate', () => {
  if (mainWindow == null) {
    createWindow()
  }
})

Add new scripts in your package.json

"scripts": {
  "dev:electron": "cross-env ARMONIA_TARGET=electron vite",
  "build:electron": "cross-env ARMONIA_TARGET=electron vite build",
}

Run the project with:

$ pnpm dev:electron

Build the project with:

$ pnpm build:electron

---

For SSR

Create the file src/entry-server.ts, it will be automatically discovered by Armonia. This will be your main entry point for the server-side code and it will run on node.

// src/entry-server.ts

// import the ssr manifest
import manifest from 'ssr:manifest'

// import the index.html string
import template from 'ssr:template'

export async function render(req: Request): Promise<string> {
  // execute your custom logic to render the page
  const app = await createAppToRoute(req.originalUrl)

  const appHtml = await renderToString(app, ctx)

  // inject the template
  return template
    .replace('</head>', `${preloadLinks}</head>`)
    .replace('<div id="app"></div>', `<div id="app">${appHtml}</div>`)
}

Add new scripts in your package.json

"scripts": {
  "dev:ssr": "cross-env ARMONIA_TARGET=ssr vite",
  "build:ssr": "cross-env ARMONIA_TARGET=ssr vite build",
}

Run the project with:

$ pnpm dev:ssr

Build the project with:

$ pnpm build:ssr

---

For SSG

Follow the SSR steps.

Update your vite.config.ts to support SSG:

// vite.config.ts
armonia({
  ssg: {
    async staticRender({ render }) {
      const code = await render('/')

      // return a list file and text
      return [
        {
          id: '/index.html',
          code
        }
      ]
    }
  }
})

staticRender will be executed when building the SSG target, render is the name of the exported function from the src/entry-server.ts file.

Add new scripts in your package.json

"scripts": {
  "build:ssg": "cross-env ARMONIA_TARGET=ssg vite build",
}

Run the project in ssr:

$ pnpm dev:ssr

Build the project with:

$ pnpm build:ssg

---

Roadmap

See the open issues for a list of proposed features (and known issues).

• Add support for Capacitor
• Provide examples and templates for react and svelte
• Stabilize the API
• Improve the documentation
• Implement a specialized CLI
• Actually do a proper CHANGELOG
• Workflow, everybody likes workflows
• Tests, tests and more tests

Contributing

First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please try to create bug reports that are:

• Reproducible. Include steps to reproduce the problem.
• Specific. Include as much detail as possible: which version, what environment, etc.
• Unique. Do not duplicate existing opened issues.
• Scoped to a Single Bug. One bug per report.

Please adhere to this project's code of conduct.

Support

Reach out to the maintainer at one of the following places:

• GitHub discussions
• Discord

License

This project is licensed under the MIT license.

See LICENSE for more information.

---

docs  ·  GitHub Nucleo Armonico  ·  Discord