This document describes how to build and test new components. The Dapr runtime and all of its components are written in Go. If you are completely new to the language you can take a tour of its features. For building your first component, using an existing one as a template is as a great way to get started.
We recommend creating a folder for Dapr and clone all repositories in that folder.
mkdir dapr
# Clone dapr
git clone https://github.com/dapr/dapr.git dapr/dapr
# Clone component-contrib
git clone https://github.com/dapr/components-contrib.git dapr/components-contrib
- Create your component directory in the right component directory.
- Copy component files from the reference component to your component directory.
- Add Go unit test files for your component.
- Add conformance tests for your component.
Type | Directory | Reference | Docs |
---|---|---|---|
State | components-contrib/state | Redis | concept, howto, api spec |
Pubsub | components-contrib/pubsub | Redis | concept, howto, api spec |
Bindings | components-contrib/bindings | Kafka | concept, input howto, output howto, api spec |
Secret Store | components-contrib/secretstore | Kubernetes, Azure Keyvault | concept, howto |
Middleware | components-contrib/middleware | Oauth2 | concept, howto |
Name Resolution | components-contrib/nameresolution | mdns | howto |
make test
make lint
- Make sure you clone the
dapr/dapr
anddapr/components-contrib
repositories side-by-side, within the same folder. - In case of compatibility issues between
dapr/dapr
anddapr/compoments-contrib
go.mod
files during build, checkout the latest released version ofdapr/dapr
. - Replace
github.com/dapr/components-contrib
with a reference to the locally-clonedcomponents-contrib
:go mod edit -replace github.com/dapr/components-contrib=../components-contrib
- Register your components by creating a file (in the
dapr/dapr
repo) incmd/daprd/components
, similar to the ones in the folder (one file per component). - Build debuggable dapr binary
make modtidy-all make DEBUG=1 build
- Replace the installed
daprd
with the test binary (the Dapr CLI will then use the test binary):# Back up the current daprd cp ~/.dapr/bin/daprd ~/.dapr/bin/daprd.bak cp ./dist/darwin_amd64/debug/daprd ~/.dapr/bin
Linux debuggable binary:
./dist/linux_amd64/debug/daprd
Windows debuggable binary:.\dist\windows_amd64\debug\daprd
macOS (Intel) debuggable binary:./dist/darwin_amd64/debug/daprd
macOS (Apple Silicon) debuggable binary:./dist/darwin_arm64/debug/daprd
- Prepare your test app (e.g. see the binding tutorial sample apps: https://github.com/dapr/quickstarts/tree/master/tutorials/bindings/)
- Create a YAML for the component in './components' under app's directory (e.g. bindings tutorial: https://github.com/dapr/quickstarts/blob/master/tutorials/bindings/components)
- Run your test app using Dapr CLI.
- Make sure your component is loaded successfully in the daprd log.
- Create a Pull Request to add your component in component-contrib repo
- Get the approval from maintainers
- Fetch the latest
dapr/dapr
repo - Update components-contrib in
dapr/dapr
'sgo.mod
and ensure thatcomponents-contrib
is updated to the latest version# In the folder where the dapr/dapr repo was cloned go get -u github.com/dapr/components-contrib@master make modtidy-all
- Register your components by creating a file (in the
dapr/dapr
repo) incmd/daprd/components
, similar to the ones in the folder (one file per component). - Create a pull request in dapr/dapr.
API versioning of Dapr components follows the same approach as Go modules where the unstable version (v0) and first stable version (v1) are contained in the root directory of the component package. For example v1 of the Redis binding component is located in bindings/redis
. Code changes may continue in this package provided there are no breaking changes. Breaking changes include:
- Renaming or removing a
metadata
field that the component is currently using - Adding a required
metadata
field - Adding an optional field that does not have a backwards-compatible default value
- Making significant changes to the component's behavior that would adversely affect existing users
In most cases, breaking changes can be avoided by using backward compatible metadata
fields. When breaking changes cannot be avoided, here are the steps for creating the next major version of a component:
- Create a version subdirectory for the next major version (e.g.
bindings/redis/v2
,bindings/redis/v3
, etc.) - Copy any code into the new subdirectory that should be preserved from the previous version
- Submit your component as described in the previous section
- Register your components by creating a new file (in the
dapr/dapr
repo) incmd/daprd/components
, without removing the file for the previous version. This time, append the new major version to the name, e.g.redis/v2
. - Validate your component as described previously