Getting started

Learn how to build Privatefolio from source.

Prerequisites

To build & run the project, you need to have the following build dependencies installed:

node -v
# v22.15.0
npm -v
# 11.3.0
yarn -v
# 1.22.22
bun -v
# 1.2.12

Node.js

It’s recommended to install Node.js through NVM (Node Version Manager), and to install Yarn through NPM.

On Windows, get it from coreybutler/nvm-windows. On Linux, get it from nvm-sh/nvm.

Afterwards, upgrade NPM and install Yarn:

npm install -g npm
npm install -g yarn

Windows

Install the latest version of Python and add it to your PATH.

python --version
# 3.13.3

Afterwards, install Bun:

powershell -c "irm bun.sh/install.ps1|iex"

Ubuntu

Ensure these development dependencies are installed:

sudo apt update && sudo apt -y upgrade
sudo apt install libnss3-dev libatk1.0-0 libatk-bridge2.0-0 libgdk-pixbuf2.0-0 libgtk-3-0 -y

Afterwards, install Bun:

curl -fsSL https://bun.sh/install | bash

Install

Before we can build the project from source, we also need to install the project dependencies:

yarn
yarn build

On Ubuntu, you need to install the set the permissions for the chrome-sandbox file:

sudo chown root:root packages/electron/node_modules/electron/dist/chrome-sandbox
sudo chmod 4755 packages/electron/node_modules/electron/dist/chrome-sandbox

Development

Run the project in development mode, to see your code changes in real-time.

yarn dev

Build native apps

To build the native apps, run any of the following commands:

# desktop apps
yarn bundle:win
yarn bundle:linux
yarn bundle:mac
yarn bundle:mac-x64
# mobile apps
yarn bundle:android
yarn bundle:ios

Now you can run the artifacts from these paths:

• Windows ./packages/electron/out/Privatefolio\ Setup\ 2.0.0-beta.44.exe
• Linux sudo dpkg -i ./packages/electron/out/privatefolio-electron_2.0.0-beta.44_amd64.deb
• MacOS Arm64 ./packages/electron/out/Privatefolio-2.0.0-beta.44-arm64.dmg
• MacOS Intel ./packages/electron/out/Privatefolio-2.0.0-beta.44.dmg
• iOS ./packages/expo/out/ios/Privatefolio.ipa
• Android ./packages/expo/out/android/app-release.apk

Build docker image

yarn docker:build

Testing

After making changes to the code, you can run the tests to see if anything broke.

yarn test
yarn test:bun # special test that has to run separately to ensure sqlite3 is compatible with bun:sqlite
yarn test:ci # running all tests in CI mode

To run a single test file:

cd packages/backend
yarn test <test-file>
yarn test test/tags/tags-api.test.ts

Tips & Know-how

Add a package as a dependency to another

Note: you need to specify a version due to this bug.

yarn workspace privatefolio-frontend add [email protected]
yarn workspace privatefolio-frontend remove privatefolio-backend
yarn workspaces info

Add a dependency to a package

yarn workspace privatefolio-frontend add react
yarn workspace privatefolio-frontend remove react

NPM utils

npm list ms # List all packages that depend on ms

Yarn utils

yarn list ms # List all packages that depend on ms
yarn upgrade-interactive # Upgrade all packages to the latest version
yarn cache clean # Clean the cache

Troubleshooting

Electron

Data is persisted in the following directories:

1. Windows:

   • Updater logs: C:\Users\daniel\AppData\Local\privatefolio-electron-updater
   • Electron logs: C:\Users\daniel\AppData\Roaming\Privatefolio\logs
   • User data: C:\Users\daniel\AppData\Roaming\Privatefolio\data
   • App config: C:\Users\daniel\AppData\Roaming\Privatefolio\config.json
   • App code: C:\Users\daniel\AppData\Local\Programs\Privatefolio

2. Linux:

   • Electron logs: ~/.config/Privatefolio/logs
   • User data: ~/.config/Privatefolio/data
   • App config: ~/.config/Privatefolio/config.json

You can also package the app without building the binaries:

cd packages/electron
yarn package

And run the executable ./out/Privatefolio-win32-x64/Privatefolio.exe.