logseq/docs/develop-logseq.md

Develop Logseq

Requirements

• Node.js (See build.yml for allowed version) & pnpm
• Java & Clojure. (If you run into Execution error (FileNotFoundException) at java.io.FileInputStream/open0 (FileInputStream.java:-2). -M:cljs (No such file or directory), it means you have a wrong Clojure version installed. Please uninstall it and follow the instructions linked.)

Clone project

This is a required step before doing any development or production builds.

git clone https://github.com/logseq/logseq
cd logseq

Browser development

Development

pnpm install
pnpm watch

Then open the browser http://localhost:3001.

REPL setup

VSCode + Calva

With pnpm watch running, it should prints shadow-cljs - nREPL server started on port 8701

You may connect to the nREPL server with:

cmd + shift + p -> Calva: Connect to a Running REPL Server in the Project -> logseq -> shadow-cljs->:app ->localhost:8701

(change :app to :electron if you want to connect to the main thread of the Electron app)

Open a dev environment (Browser dev app on localhost:3000 or Desktop dev app), then you can play REPL on the current editing file:

cmd + shift + p -> Calva: Load/Evaluate Current File and its Requires/Dependencies

Connect to the web-worker context

Emacs + Cider

When connecting to a CLJ nrepl (NOTE: if you are already in a CLJS nrepl, use :cljs/quit to go back to CLJ nrepl), you may run (shadow.user/worker-repl), or use (shadow/nrepl-select :app {:runtime-id <id-num>}) to connect to a web-worker context.

[!TIP] you can find the <id-num> in http://localhost:9630/runtimes

Intellij Idea/Cursive-ide

The setup is almost same as Calva except it requires switching REPL from CLJ to CLJS manually.

1. Start nrepl with pnpm watch, wait until it prints shadow-cljs - nREPL server started on port 8701
2. Create a new remote REPL run configuration:
   • Connection type: nREPL
   • Context module: logseq
   • :radio_button: Use port from file with localhost
   • :radio_button: Use standard port file
3. Start the remote REPL, now you are in CLJ REPL instead of target CLJS REPL
4. In the REPL, execute (shadow.cljs.devtools.api/repl :app)
5. Verify you are in CLJS REPL by executing (js/alert "hello world"), it should show an alert dialog in the browser window

[!WARNING] You need open the browser dev app (http://localhost:3001) before executing step 5, otherwise it will throw an error:

### Production Build

bash pnpm release

The released files will be at `static/` directory.

## Desktop app development

### Development

1. Install npm packages for building the desktop app

bash pnpm install cd static pnpm install cd ..

2. Compile to JavaScript and open the dev app

bash pnpm watch

Wait until watch reports Build Completed. for :electron and :app.

Then, run the following command in a different shell.

If you have opened desktop logseq, you should close it. Otherwise, this command will fail.

pnpm dev-electron-app

Alternatively, run `bb dev:electron-start` to do this step with one command. To
download bb, see https://github.com/babashka/babashka#installation.

3. (Optional) Update dependencies if `resources/package.json` has changed since
   the last time you used dev Logseq.

bash

pull new changes

git pull

cd static && pnpm install && cd ..

Here `static/` is generated by `pnpm watch` command.

### Production Build

Build a release:

bash pnpm release-electron

The final released binaries or installers will be at `static/out/`.

## DB sync

DB sync can be run locally in one of two ways as described in the following
sections. To use a local sync approach, the app must be built with
`$ENABLE_DB_SYNC_LOCAL` e.g. `ENABLE_DB_SYNC_LOCAL=true pnpm watch`. For more
about db sync, see [its readme](/deps/db-sync/README.md).

### DB sync Cloudflare Worker adapter

Build and run a Cloudlare worker locally

bash cd deps/db-sync pnpm install pnpm release

This migration is a one time setup

cd worker && wrangler d1 migrations apply DB --local && cd - pnpm dev

When testing

### DB sync Node adapter (self-hosted)

Build and run the Node.js adapter for self-hosted DB sync.

bash cd deps/db-sync pnpm install DB_SYNC_PORT=8787 \ COGNITO_ISSUER=https://cognito-idp.us-east-2.amazonaws.com/us-east-2_kAqZcxIeM \ COGNITO_CLIENT_ID=1qi1uijg8b6ra70nejvbptis0q \ COGNITO_JWKS_URL=https://cognito-idp.us-east-2.amazonaws.com/us-east-2_kAqZcxIeM/.well-known/jwks.json \ pnpm build:node-adapter

DB_SYNC_PORT=8787 \ COGNITO_ISSUER=https://cognito-idp.us-east-2.amazonaws.com/us-east-2_kAqZcxIeM \ COGNITO_CLIENT_ID=1qi1uijg8b6ra70nejvbptis0q \ COGNITO_JWKS_URL=https://cognito-idp.us-east-2.amazonaws.com/us-east-2_kAqZcxIeM/.well-known/jwks.json \ pnpm start:node-adapter ```

Optional environment variables:

• DB_SYNC_DATA_DIR (defaults to data/db-sync)

Notes:

• The Cognito values above match ENABLE_DB_SYNC_LOCAL=true pnpm watch default auth config.
• For production builds, use the production Cognito pool values from src/main/frontend/config.cljs.