synectic

Synectic Integrated Development Environment

GitHub Workflow Status GitHub GitHub release

Synectics is a problem solving methodology that stimulates thought processes of which the subject may be unaware (Wikipedia). Synectic IDE is a fundamentally different type of IDE, focused on supporting a human-oriented view of problem solving in software development. Synectic promotes context-specific functionality that compliments and enhances human cognition, memory, and reasoning. As a research prototype, this software has no expressed warranty or guarantees and should be treated as experimental software.

The rationale and principles that guide the design of Synectic can be found in DESIGN. The complete set of programming languages, tools, bundlers, packagers, frameworks, and plugins included in Synectic, along with the configuration requirements, can be found in ARCHITECTURE. Synectic is released under an MIT license, which can be found in LICENSE.

Versioning within this project adheres to the rules of Semantic Versioning 2.0.0.

Usage

Prerequisites

Synectic requires the host system to have Git installed and available in order to natively execute git commands (version 2.5+ is recommended for git worktree support).

Installation

Distributable versions of Synectic are available in various formats for MacOS, Linux, and Windows:

macOS Linux Windows

:warning: Warning :warning:: Every operating system uses code signing to establish stable identities for programs that don’t change when new versions are released, and to secure the software update process. Windows and macOS additionally use signing as a way to block malware.

This is experimental research software, and is not intended for use in production environments. As such, we are not able to purchase signing keys for Windows and macOS. This means that you will see a warning when installing Synectic on Windows and macOS. You will need to click through the warning to install Synectic. If you are not comfortable with this, please do not install Synectic.

See the Installation Guide for guidance on using unsigned builds of Synectic.

Packaged

Development

To run Synectic from source, or to contribute to the project, follow the instructions below.

We recommend using VSCode with the following plugins:

Source Installation

To install Synectic from source, use the following steps:

  1. Install Node.js.
  2. Install Yarn Package Manager (npm/npx can also be used, but yarn is preferred).

  3. Clone this repository:

    git clone git@github.com:EPICLab/synectic.git

  4. Move into the project root directory:

    cd synectic

  5. Install project dependencies:

    yarn install

  6. Build the main/preload/renderer modules:

    yarn build

  7. Start Synectic in watch mode:

    yarn watch

CLI

Make sure to follow the Source Installation instructions before using the CLI. The following commands can be used from within the project root directory:

Project Structure

This project is based on the Vite Electron Builder Boilerplate template, which was written following the latest safety requirements, recommendations and best practices. The structure of the project is similar to a monorepo. The entire scource code of the project is divided into three modules (packages) that are each bundled independently:

Schematically, the structure of the application and the method of communication between packages can be depicted as follows:

flowchart TB;

packages/preload <-. IPC Messages .-> packages/main

    subgraph packages/main["packages/main (Shared beatween all windows)"]
    M[index.ts] --> EM[Electron Main Process Modules]
    M --> N2[Node.js API]
    end

subgraph Window["Browser Window"]
    subgraph packages/preload["packages/preload (Works in isolated context)"]
    P[index.ts] --> N[Node.js API]
    P --> ED[External dependencies]
    P --> ER[Electron Renderer Process Modules]
    end


    subgraph packages/renderer
    R[index.html] --> W[Web API]
    R --> BD[Bundled dependencies]
    R --> F[Web Frameforks]
    end
    end

packages/renderer -- Call Exposed API --> P

Context Isolation

The main and preload packages are built in library mode after compiling from TypeScript to JavaScript. The renderer package builds as a regular web app.

Because the renderer works and builds like a regular web application, we can only use dependencies that support the browser or compile to a browser-friendly format. This means that we can use React (or any frontend dependencies we want) in the renderer, but we CANNOT use any native Node.js APIs, such as, systeminformation.

Using any Node.js APIs in the renderer layer will cause the application to crash. Instead, any Node.js runtime APIs that are needed in the frontend have been exported from the preload package and exposed via the electron.contextBridge.exposeInMainWorld method.

The exposeInMainWorld method is called automatically by the unplugin-auto-expose, so we can import and call these methods within the renderer package by using the #preload alias.

Working with Electron API

Although the preload has access to all of Node.js’s API, it still runs in the BrowserWindow context, so a limited set of electron modules are available in it. Check the Electron documentation for a full list of available methods.

All other electron methods can be invoked in the main module.

As a result, the architecture of interaction between all modules is as follows:

sequenceDiagram
renderer->>+preload: Read data from file system
preload->>-renderer: Data
renderer->>preload: Maximize window
activate preload
preload-->>main: Invoke IPC command
activate main
main-->>preload: IPC response
deactivate main
preload->>renderer: Window maximized
deactivate preload

Read more about Inter-Process Communication

Modes and Environment Variables

:warning: Warning :warning:: To prevent accidentally leaking env variables to the client, only variables prefixed with VITE_ are exposed to any Vite-processed code.

All environment variables are set as part of the import.meta, and can be accessed via import.meta.env. The mode option is used to specify the value of import.meta.env.MODE and the corresponding environment variables files that need to be loaded.

By default, there are two modes:

When running the build script, the environment variables are loaded from the following files in the project root:

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified env mode
.env.[mode].local   # only loaded in specified env mode, ignored by git

See more about Vite environment variables here: envPrefix

Releases

Installation is required; see CLI for installation instructions. The following commands can be used from within the project root directory:

Caveats

The Node.js ecosystem is currently undergoing a transition from CommonJS to ES Modules (ESM) in upstream libraries, and Electron is no exception. electron@28.0.0 will be the first stable release of Electron to support ESM, and is set to release on 2023-12-05 according to the Electron Timelines. Given the dependency on Electron, Synectic will not be able to take advantage of ESM until this time. There is a ES Modules (ESM) in Electron tutorial describing the steps required in order to take advantage of ESM once 28.0.0 is generally available.

We can continue to use CJS modules, and ESM modules that provide a CJS fallback, until electron@28.0.0 is released. But there are a few modules that are ESM-only, and are listed here in the hopes that they can be included in Synectic in a future release:

Both of these modules are ESM-only, and provided by the same developer. The developer consistently references a particular GitHub Gist, Pure ESM package, whenever they are asked about CommonJS support.

Contributors

We welcome contributions to this open source project on Github. When contributing, please follow the Contributing Code Guide. Also, any new contributors should include a commit that updates this README.md document to include your name and a link to your GitHub profile page (unless you wish to be anonymous).

Contributors[^1] [^1]: Contributor images made with contrib.rocks.

Continuous Integration

Workflow graph

Publishing

Note: This template configured only for GitHub public repository, but electron-builder also supports other update distribution servers. Find more in electron-builder docs.

Build web resources

The main and preload packages are built in library mode after compiling from TypeScript to JavaScript. The renderer package builds as a regular web app.

Compile App

The next step is to package a ready to distribute Electron app for macOS, Windows and Linux with “auto update” support out of the box.

To do this, use [electron-builder]:

This site is open source. Improve this page.