Synectic Development Environment

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:

⚠️ 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.

Development

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

Recommended Environment

We recommend using VSCode with the following plugins:

• ESLint
• Prettier

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:

• yarn watch - Start Electron app in watch mode.
• yarn build - Build app but for local debugging only.
• yarn lint - Lint the code using ESLint.
• yarn typecheck - Run a TypeScript check.
• yarn test - Run all unit, integration, and e2e tests.
• yarn format - Reformat all codebase to project code style.
• yarn bundle - The command will execute the same steps as yarn build, but afterwards will call the Conveyor site task to request a full build of the download/repository site, before Publishing through GitHub.

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:

• packages/renderer - Responsible for the contents of the application window. In fact, it is a regular web application. In developer mode, you can even open it in a browser. The development and build process is the same as for classic web applications. Access to low-level API electrons or Node.js is done through the preload layer.
• packages/preload - Contain Electron preload scripts. Acts as an intermediate bridge between the renderer process and the API exposed by electron and Node.js. Runs in an isolated browser context, but has direct access to the full Node.js functionality.
• packages/main - Contain Electron main script. This is the main process that powers the application. It manages creating and handling the spawned BrowserWindow, setting and enforcing secure permissions and request handlers. You can also configure it to do much more as per your need, such as: logging, reporting statistics and health status among others.

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

Loading

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

Loading

Read more about Inter-Process Communication

Modes and Environment Variables

⚠️ 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:

• production is used by default
• development is used by yarn watch script

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:

• yarn release - executes yarn version plugin to initiate a major semver version bump, generate a new version.js using genversion, stage and commit all relevant version files, generate a new annotated Git tag, and atomically push changes to the remote repository to trigger GitHub Actions.

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:

• dot-prop
• find-up

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).

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

• Nicholas Nelson (@nelsonni)
• Andrea Tongsak (@andrealit)
• Jett Seale (@jettseale)
• Brandon Dring (@El_Dringo_Brannde)
• Marjan Adeli (@Marjan-Adeli)
• Hayden Coffey (@hcoffey1)
• Lauren Gastineau (@laurengastineau)
• Samarendra Hedaoo (@knightsamar)