logseq/docs/develop-logseq.md

# Develop Logseq
## Requirements

- [Node.js](https://nodejs.org/en/download/) (See [build.yml](https://github.com/logseq/logseq/blob/master/.github/workflows/build.yml) for allowed version)  & [pnpm](https://pnpm.io/installation)
- [Java & Clojure](https://clojure.org/guides/getting_started). (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.

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

## Browser development

### Development

```bash
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:
>
> ```No available JS runtime. See https://shadow-cljs.github.io/docs/UsersGuide.html#repl-troubleshooting=> nil```


### 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`.