Electron¶

Create desktop applications with Dazzler and Electron.

Tip

Quickstart with a Github template: https://github.com/T4rk1n/dazzler-electron-template

Requirements¶

Install npm first: https://www.npmjs.com/
Install electron dependencies: pip install dazzler[electron]

For developing and running app locally, you will need to install electron somewhere on your path: npm i -G electron

Commands¶

Run a local instance of your application: dazzler electron app.py
Package your application: dazzler electron-build app.py
Publish: dazzler electron-build app.py --publish

Configuration¶

Dazzler electron requires a config file to work properly. Generate a new config with all the defaults: dazzler dump-configs dazzler.toml.

To override the config file used by dazzler, you can provide the -c option before the command (eg: dazzler -c production.toml electron-build app.py).

The target application must call start() in the main section.

from dazzler import Dazzler
app = Dazzler(__name__)

if __name__ == '__main__':
    app.start()

Page Windows¶

To create a window, add a page to electron.windows with the page name. If the application contains only one page, it will automatically create a window for it.

[electron]
windows = ["main"]

A window will be created for each entry if a matching Page is found.

Window settings¶

To set window attributes like width and height, add settings to the page with the Page parameter electron_window.

from dazzler.system import Page

page = Page(
    __name__,
    'component',
    electron_window={'width': 1048, 'height': 768}
)

Default size¶

Defaults size for all windows can be set with configs:

[electron.window_size]
width = 800
height = 600
fullscreen = false

Window state at runtime¶

Use WindowState to read and control the window state after the application has started.

from dazzler.system import Page
from dazzler.components.core import Text, Container
from dazzler.components.electron import WindowState

page = Page(
    'dazzler_electron',
    Container([
        WindowState(identity='window'),
        Box([Text('Width: '), Text(identity='width-output')])
    ])
)

page.tie('width@window', 'text@width-output')

Save window size¶

Save the window size on quit and reload them when re-opening the application.

[electron]
save_window_size = true

Multiple instances¶

To allow multiple instances of the application, set the port_range config to true to have a new port assigned for each new instances.

port = 62895
port_range = true

Loading window¶

The [electron.loading_window] config section is used to create a loading window on startup if the server instance has to load data and takes longer to start.

The window look can be customized in with either a custom html file or adding a header/footer.

[electron.loading_window]
enabled = true
html_file = "/path/to/html"
header = "<div>Header</div>"
footer = "<div>Footer</div>"

The options config is the window settings for the loading window, the defaults values place a small window in the middle of the screen without a frame.

Slow to load on windows

The packaged executable is slow to load the initial window on Windows due to Windows Defender. You need to sign your application to load instantly, the loading window is also affected by that.

Packaging¶

Packaging the application needs a few config to be setup, [electron.metadata] section should be filled up, the app_name needs to set for the name of the executable.

The default target is dir which output the executable in a directory. The default output directory is electron and can be changed with the command parameter -o. Inside that folder will be generated the package.json and node_modules installed for the build, the target files can be found in the dist folder and the electron executable is located in dist/{platform}-unpacked directory with the given app_name.

Publish¶

Publish the application using the parameter --publish for the electron-build command. electron.publish.provider must set in the configs with the related options.

Evaluating if the application is packaged¶

Use is_compiled() to determine if the application is running when compiled.

from dazzler import Dazzler
from dazzler.electron import is_compiled

app = Dazzler(__name__)
...
if __name__ == '__main__':
    if is_compiled():
        app.start('')
    else:
        app.start('--reload')

Limitations¶

No support for pages_directory config option.
Auth system should be disabled.
Session system should be disabled.

Development tips¶

Do not include secrets inside the app, the binary can easily be decompiled.
If there’s an error in the startup, electron will still be alive and after a while will consume lots of memory/cpu resources. Kill the processes manually via command line or task manager on windows.

If porting an existing web app:

Do not connect directly to databases, create external services api and fetch from them.
If loading lot of data on startup, think of putting that inside a binding instead so the startup is faster.