logseq/docs/develop-logseq.md

Develop Logseq

Requirements

• Node.js (See build.yml for allowed version) & Yarn
• 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

yarn
yarn watch

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

REPL setup

VSCode + Calva

With yarn 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 yarn 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 yarn release

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

## Desktop app development

### Development

1. Install npm packages for building the desktop app

bash yarn install cd static yarn install cd ..

2. Compile to JavaScript and open the dev app

bash yarn 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.

yarn 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 && yarn install && cd ..

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

### Production Build

Build a release:

bash yarn 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 yarn 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 yarn install yarn release

This migration is a one time setup

cd worker && wrangler d1 migrations apply DB --local && cd - yarn 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 yarn 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 \ yarn 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 \ yarn 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 yarn watch default auth config.
• For production builds, use the production Cognito pool values from src/main/frontend/config.cljs.