Configuring Armonia #

Config File #

Config Targets #

Armonia supports multiple targets within a single project, therefore each target gets its own configuration.

// vite.config.js
export default {
  plugins: [
    armonia({
      electron: { ... },
      ssr: { ... },
      ssg: { ... }
    })
  ]
}

To choose a target, use the target options:

armonia({
  target: 'ssr'
})

Or use the env variable ARMONIA_TARGET using cross-env:

$ pnpm i cross-env -D

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

Environment Variable #

It is suggested that you use the environment variable instead of hard-coding a target, it will be more convenient in the long run.

The env variable ARMONIA_TARGET is needed since the vite CLI do not accepts unknown options, see the PR 1188 for more information.

Options #

target #

• Type: string

• Default: spa

  The default target, you should use an environment variable instead.

  Available targets: spa ssr ssg electron

Electron Options #

electron.argv #

• Type: string[]

  Specify the args to pass to the electron cli.

electron.main #

• Type: string

  The electron main file, it will be de file containing the code to run the electron applications.

  Omit the file extension to resolve .js and .ts automatically.

  Armonia will look for:

  • electron/main.{ts,js}
  • electron/index.{ts,js}
  • electron/electron.{ts,js}
  • src-electron/main.{ts,js}
  • src-electron/index.{ts,js}
  • src-electron/electron.{ts,js}
  • src-electron/electron-main.{ts,js}
  • src/electron.{ts,js}
  • src/electron-main.{ts,js}

electron.preload #

• Type: string

  The electron preload file.

  Omit the file extension to resolve .js and .ts automatically.

  Armonia will look for:

  • electron/preload.{ts,js}
  • src-electron/preload.{ts,js}
  • src-electron/electron-preload.{ts,js}
  • src/preload.{ts,js}
  • src/electron-preload.{ts,js}

electron.bundler #

• Type: 'packager' | 'builder' | false

  The electron bundler to use during build, automatically resolved by Armonia.

  You need to install one of the bundler in order to use it:

  $ pnpm i electron-builder -D
  

  $ pnpm i electron-packager -D
  

  Set it to false to disable bundling, useful if you wish to bundle electron manually.

  Refer to the official bundler documentation for more information:

  • Electron Builder
  • Electron Packager

electron.packager #

• Type: ElectronPackagerOptions

  The electron-packager options to use during build.

electron.builder #

• Type: ElectronBuilderOptions

  The electron-builder options to use during build.

electron.transformPackageJson #

• Type: (pkg: Record<string, any>) => void | Promise<void>

  Hook for transforming the package.json. The hook receives the content of the package.json as an object.

  Edit the object that will be saved and used to build electron.

  This hook is most used for fine tuning the generated package.json, such as for example, delete unused dependencies.

electron.config #

• Type: UserConfig

  Overwrite the vite config for this target.

SSR Options #

ssr.ssr #

• Type: boolean | string

• Default: undefined

  Specify the default SSR entry, similar to build.ssr, this value can be a string to directly specify the SSR entry, or true, which requires specifying the SSR entry via rollupOptions.input.

  This options is automatically resolved by Armonia.

  Armonia will look for:

  • src/entry-server.{ts,js}

ssr.serverRoot #

• Type: string

• Default: 'www'

  Specify the directory that contains the server static assets, including the static generated files (relative to build.outDir).

ssr.writeManifest #

• Type: boolean

• Default: false

  Enable or disable the output of ssr-manifest.json and index.html.

ssr.transformTemplate #

• Type: (html: string) => Promise<string | void> | string | void

  Apply a transformation to the index.html file, note this will run after vite and just before render is called. It will not run when render is called.

ssr.render #

• Type: (context: SSRRenderContext) => Promise<string | void> | string | void

  Hook to invoke a custom renderer function, due to the nature of SSR rendering, you may want to use this function to replicate any custom server-side logic.

  An example usage:

  render({ req, res, template, manifest, ssr }) {
    const html = ssr.customRenderFunction(req, res, template, manifest)
  
    // Armonia will serve this exact string as text/html
    return html
  }
  

ssr.config #

• Type: UserConfig

  Overwrite the vite config for this target.

SSG Options #

ssg.ssr #

• Inherit - See ssr.ssr

ssg.serverRoot #

• Inherit - See ssr.serverRoot

ssg.writeManifest #

• Inherit - See ssr.writeManifest

ssg.transformTemplate #

• Inherit - See ssr.transformTemplate

ssg.staticRender #

• Type: (ssr: Record<string, any>, config: ResolvedConfig) => Promise<SSGFile[]> | Promise<void> | SSGFile[] | void

  Render the SSG target, return an array containing a list of file id and code, the files will be written under ssg.serverRoot.

  An example usage:

  async staticRender({ render }) {
    const code = await render()
  
    return [
      {
        id: '/index.html',
        code
      }
    ]
  }
  

ssg.config #

• Type: UserConfig

  Overwrite the vite config for this target.