Click to expand
While developing the following command will build the app and start electron in debug mode with http cache disabled:
$ pnpm dev
It's also handy to develop in watch mode so that your changes to the code are immediately recompiled. For this you need two terminal windows:
# Terminal 1
$ pnpm -w watch:electron
# Terminal 2
$ pnpm -w start:electronAfter making your changes, go in the deltachat/electron Dev-console and press F5 or Cmd+R to reload the frontend process.
Note: this only applies to the frontend code in
src/renderer. To build the main process you still need to usepnpm -w build:electronand then restart the deltachat-desktop process. (pnpm -w start:electron)
The primary command for checking any changes made to the code is:
pnpm -w checkThis command in turn splits up into the following commands:
pnpm -w check:types-> Runstscto make sure theTypeScriptcode is okpnpm -w check:lint-> RunseslintwithTypeScriptrules to check for common bad practices in all.js,.tsand.tsxfilespnpm -w check:format-> RunsPrettierwith rules inspired byStandardJSto check formatting in all.scss,.js,.ts,.tsx,.jsonand.mdfilespnpm -w check:log-conventions-> checks for illegal use ofconsole.log()
Sometimes eslint complains on code lines that for whatever reason doesn't fit well with the project style. Lines like this can be ignored by using // eslint-disable-next-line on the line prior to the line you would like to ignore:
// eslint-disable-next-line
const unused_var = 'This line would normally trigger some linting errors'We set up the linting using this guide
If you work with SCSS make sure you read docs/STYLES.md
Running pnpm -w check:lint when using VS Code will make VS Code display the found problems.
If you're unsure it's always safe to run pnpm -w check to check everything. If you know what you're doing you can run the lower level commands for a more fine grained check.
If the code style check fails you can try to have it fixed for you. The primary command for doing this is:
pnpm -w fixThis command in turn splits up into the following commands:
pnpm -w fix:lint-> Runseslintto attempt fixing any issues in all.js,.tsand.tsxfilespnpm -w fix:format-> RunsPrettierto attempt fixing formatting in all.scss,.js,.ts,.tsx,.jsonand.mdfiles
If you're unsure it's always safe to run pnpm -w fix to fix everything. If you know what you're doing you can run the lower level commands for a more fine grained fix.
Running pnpm -w test runs the unit tests.
Info here is outdated, at the moment there is no E2E testing anymore.
Run npm test-e2e for end-to-end (E2E) testing. In E2E testing, TestCafe clicks through the app and simulates normal usage.
You need to provide a temporary email account generation token via the environment variable DCC_NEW_TMP_EMAIL. (ask contributors on how to get one of these tokens)
Install the transifex client and get added to the Delta Chat App project.
And periodically we can run the following command to get the new translation strings from translators:
pnpm -w translations:update
When you need to modify language strings do it as a PR on English language strings in the Android repo. It is in a language other than English do it in Transifex.
See the Add experimental language strings section for instructions on how to add new language strings.
⚠ Information on this section might be deprecated. [TODO update this section]
Sometimes you need to add new language strings, but don't want to push them to transifex immediately. Some potential reasons include:
- the strings may be adjusted in the near future
- the relevant PR may not get merged
- you don't have push rights to the transifex language repo
To still be able to implement new language strings, you can add them to the _locales/_untranslated_en.json
file. You can also overload every other language string if you need to.
The syntax is exactly the same as for all other _locales/*.json files.
Example:
{"foobar_desktop": {"message": "This is a test"}}
Tip: run with the
--translation-watchflag (included inpnpm start) to start in translation watch mode - which watches the experimental language strings and hot reloads them into dc-desktop on save
There are two methods to use localized strings:
- Static usage over
window.static_translate - Dynamic usage over
i18nContext, where the component that uses this method is automatically rerendered when the user changes the language.
- in functions like message functions use
static_translate - in dialog it's generally ok to use
static_translate - in functional components use the hook/context
- in classes render functions use
<i18nContext.Consumer>{tx=>( )}</i18nContext.Consumer> - if you are unsure use
static_translate.
For the usage please look at existing code, the types and the doc comments.
Generally you just need to know that the <i18nContext.Consumer>, useTranslationFunction() and window.static_translate are the same functions.
For Continuous Integration we use GitHub Actions.
Build in production mode (development tools disabled and minified frontend code)
NODE_ENV=production pnpm -w build
# the electron target also has a shortcut that should also work on windows
cd packages/target-electron
pnpm build4production(for building on Windows you need another command to set the environment variable)
First make sure you are in the
packages/target-electrondirctory.
Generate the electron-builder.json5 file with pnpm pack:generate_config.
Possible options for pnpm pack:generate_config:
| Environment var | Effect |
|---|---|
NO_ASAR=true |
Disable asar, used for flatpack |
note: on Windows you need to enable Developer Mode in System settings > For developers before packing
If you haven't done so run pnpm build now.
Then you need to run pnpm pack:patch-node-modules to patch node_modules. (DON'T forget this step!)
So that the electron-builder afterPackHook is able to find the rpc binaries.
Start electron-builder:
| Command | Description |
|---|---|
pnpm pack:win |
Build for Windows (nsis & portable target) |
pnpm pack:mac |
Build for macOS (dmg & mas target) |
pnpm pack:linux |
Build for Linux (AppImage & deb target) |
pnpm pack:linux:dir |
Build for Linux, but just the folder, no package. This is used for Flatpak. |
For more info look at the scripts section in package.json.
The commands for windows10 appx and the App Store package for mac are currently not in the scripts section. They are useless for most people anyway, as they require special paid developer accounts or signing certificates.
mas- mac appstore buildappx- windows appstore build, you can find info on how to build a self-signed appx inAPPX_TESTING.md.
If you are building window on windows you might run into the file path limit of 260 characters. To avoid that, make a folder with a short name directly on your drive (like c.tmp).
See RELEASE.md
Some important folders and files:
├── .gihub/workflows # source of our Github Actions
├── CHANGELOG.md # what changed
├── RELEASE.md # how to make a release
├── _locales # translations
│ ├── _languages.json # central file which defines the visible languages and their native names for the users to choose
│ ├── _untranslated_en.json # new translation keys that are not yet upstreamed to the android-repo/transifex.
│ └── ...
├── bin # executable scripts for various developer tasks
├── docs # documentation
├── images # images and icons
├── packages
│ ├── frontend # the frontend / UI
│ │ ├── bin # executable scripts specific to the frontend
│ │ ├── html-dist # [generated] output from building
│ │ ├── scss # global css stylesheets
│ │ ├── src # source code
│ │ ├── static # static files that are needed
│ │ └── themes # themes
│ ├── runtime
│ │ └── runtime.ts # runtime interface that abstracts over runtime, so frontend can run on electron, tauri and browser
│ ├── shared # code that is shared between the packages
│ │ ├── shared-types.d.ts # shared types
│ │ ├── tests # tests
│ │ └── ts-compiled-for-tests # [generated] compiled code for testing
│ ├── target-browser
│ │ └── runtime-browser # runtime implementation for browsers
│ ├── target-e2e-integration-testsuite
│ ├── target-electron
│ │ ├── bin # executable scripts specific to the electron target
│ │ ├── build # scripts and files needed for packaging
│ │ ├── bundle_out # [generated] compiled+bundled js code for electron main rocess
│ │ ├── dist # [generated] output from packaging
│ │ ├── electron-builder.json5 # [generated] config file for packaging with electron-builder
│ │ ├── html-dist # [generated] bundled frontend and static resources
│ │ ├── runtime-electron # runtime implementation for electron
│ │ ├── src # source for electron main process js code
│ │ ├── static # static files that are needed
│ │ ├── stub.cjs # file that can be used for electron builder to skip signing
│ │ └── tests # tests, like a test for the account data migration function
│ └── target-tauri
├── static
│ ├── fonts # fonts
│ ├── help # help files in different languages, generated by bin/create-local-help.sh
│ └── xdcs # internal extension xdcs
└── test # old inactive tests that will be rewritten soonProblem: Strange TypeScript errors that are only visible in VS Code but the project compiles normally
Solution: Tell VS Code to use the workspace version of TypeScript instead of an built-in version more info
Can only be tested in builds that have a desktop file. The simplest way to do this is to install the appimage generated by pnpm electron-builder --linux AppImage. (Installing with AppImageLauncher)
bash:
pnpm completion bash > ~/completion-for-pnpm.bash
echo 'source ~/completion-for-pnpm.bash' >> ~/.bashrczsh:
pnpm completion zsh > ~/completion-for-pnpm.zsh
echo 'source ~/completion-for-pnpm.zsh' >> ~/.zshrcsee also: https://pnpm.io/completion
Sometimes you want to package the app for macOS for testing, but don't have the required certificates for signing it. You can set the following environment variable to skip code signing:
export CSC_IDENTITY_AUTO_DISCOVERY=false
Docs about macOS sandbox permissions:
If you want to debug how many jsonrpc calls were made you can run exp.printCallCounterResult() in the devConsole when you have debug logging enabled.
This can be useful if you want to test your debouncing logic or compare a branch against another branch, to see if your changes reduced overall jsonrpc calls.