How to use the app boilerplate
This guide shows you how to fork and set up the Ledger app boilerplate to start building a Ledger signer app.
The boilerplate showcases the Ledger Device SDK and the surrounding development tooling: Docker containers, Speculos emulator, and the Ragger test framework. It includes examples for APDU handling, UI flows, cryptography, and build/test/CI integration.
Who this is for:
- Developers beginning Ledger signer app development.
- Developers who want a concise reference for build, test, and CI logic in a Ledger signer app.
Supported devices: Nano S+, Nano X, Stax, Flex, and Nano Gen5.
Quick start
Fork the app boilerplate (C)
Click here to fork the repository and start your project.
Set up the VSCode extension
Use Ledger’s VSCode developer tools to build, run on Speculos, run functional tests, and load on a device from the VSCode UI.
Continuous Integration (CI)
Two workflows are required for app submission: Build_and_functional_tests and Guidelines_enforcer.
Build_and_functional_tests
Build_and_functional_tests builds the app and runs functional tests using Ragger and Speculos.
Guidelines_enforcer
Guidelines_enforcer calls a reusable guidelines_enforcer workflow used for submission checks.
Troubleshooting
The Guidelines_enforcer workflow fails in CI.
Review the workflow logs to identify the specific rule that failed. Common causes include missing or incorrectly formatted app metadata (in ledger_app.toml) and icon size issues. Refer to the development requirements page for the full list of checks.
Speculos does not launch on macOS. Make sure XQuartz is running and that you have enabled “Allow client connections” under XQuartz > Preferences > Security. Then restart the Docker container.
Next steps
After forking either boilerplate and reviewing the included CI workflows and guidelines, adapt the application to your project by:
- Updating metadata in
ledger_app.toml. - Implementing your APDU handlers.
- Designing UI flows that follow the graphic library usage guidelines.
When your app is ready, follow the submission process to submit it for review.
