Skip to content

Commit c66d4cc

Browse files
greenie-msftgreenie-msft
committed
Add Dapr Docs
1 parent 8bfda5b commit c66d4cc

File tree

3 files changed

+241
-0
lines changed

3 files changed

+241
-0
lines changed

‎daprdocs/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Dapr JavaScript SDK documentation
2+
3+
This page covers how the documentation is structured for the Dapr JavaScript SDK
4+
5+
## Dapr Docs
6+
7+
All Dapr documentation is hosted at [docs.dapr.io](https://docs.dapr.io), including the docs for the [JavaScript SDK](https://docs.dapr.io/developing-applications/sdks/java/). Head over there if you want to read the docs.
8+
9+
### JavaScript SDK docs source
10+
11+
Although the docs site code and content is in the [docs repo](https://github.com/dapr/docs), the JavaScript SDK content and images are within the `content` and `static` directories, respectively.
12+
13+
This allows separation of roles and expertise between maintainers, and makes it easy to find the docs files you are looking for.
14+
15+
## Writing JavaScript SDK docs
16+
17+
To get up and running to write JavaScript SDK docs, visit the [docs repo](https://github.com/dapr/docs) to initialize your environment. It will clone both the docs repo and this repo, so you can make changes and see it rendered within the site instantly, as well as commit and PR into this repo.
18+
19+
Make sure to read the [docs contributing guide](https://docs.dapr.io/contributing/contributing-docs/) for information on style/semantics/etc.
20+
21+
## Docs architecture
22+
23+
The docs site is built on [Hugo](https://gohugo.io), which lives in the docs repo. This repo is setup as a git submodule so that when the repo is cloned and initialized, the javascript-sdk repo, along with the docs, are cloned as well.
24+
25+
Then, in the Hugo configuration file, the `daprdocs/content` and `daprdocs/static` directories are redirected to the `daprdocs/developing-applications/sdks/javascript` and `static/javascript` directories, respectively. Thus, all the content within this repo is folded into the main docs site.

‎daprdocs/content/en/js-sdk-contributing/js-contributing.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
type: docs
3+
title: "Contributing to the JavaScript SDK"
4+
linkTitle: "JavaScript SDK"
5+
weight: 3000
6+
description: Guidelines for contributing to the Dapr JavaScript SDK
7+
---
8+
9+
When contributing to the [JavaScript SDK](https://github.com/dapr/js-sdk) the following rules and best-practices should be followed.
10+
11+
## Examples
12+
13+
The `examples` directory contains code samples for users to run to try out specific functionality of the various JavaScript SDK packages and extensions. When writing new and updated samples keep in mind:
14+
15+
- All examples should be runnable on Windows, Linux, and MacOS. While JavaScript code is consistent among operating systems, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}})
16+
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
17+
18+
## Docs
19+
20+
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built, this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs, keep in mind:
21+
22+
- All rules in the [docs guide]({{< ref contributing-docs.md >}}) should be followed in addition to these.
23+
- All files and directories should be prefixed with `js-` to ensure all file/directory names are globally unique across all Dapr documentation.

‎daprdocs/content/en/js-sdk-docs/_index.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
type: docs
3+
title: "Dapr JavaScript SDK"
4+
linkTitle: "JavaScript"
5+
weight: 1000
6+
description: JavaScript SDK packages for developing Dapr applications
7+
---
8+
9+
## Pre-requisites
10+
11+
- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
12+
- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
13+
- [Node version 15 or greater](https://nodejs.org/en/)
14+
15+
## Installing and importing Dapr's JS SDK
16+
17+
18+
Install the SDK with npm:
19+
```
20+
npm i @roadwork/dapr-js-sdk
21+
```
22+
23+
Import the libraries for the the given protocol you're using:
24+
25+
```javascript
26+
import { DaprClient, DaprServer } from "@roadwork/dapr-js-sdk/http";
27+
// OR (depending on the protocol)
28+
import { DaprClient, DaprServer } from "@roadwork/dapr-js-sdk/grpc";
29+
```
30+
31+
## Building blocks
32+
33+
The JavaScript SDK allows you to interface with all of the [Dapr building blocks]({{< ref building-blocks >}}).
34+
35+
### Invoke a service
36+
37+
```javascript
38+
import { DaprClient, HttpMethod } from "@roadwork/dapr-js-sdk/http";
39+
40+
const daprHost = "127.0.0.1";
41+
const daprPort = "50050";
42+
43+
async function start() {
44+
const client = new DaprClient(daprHost, daprPort);
45+
46+
//POST Request
47+
const response = await client.invoker.invoke(SERVICE_TO_INVOKE, METHOD_TO_INVOKE, HttpMethod.POST, {
48+
name: "World!"
49+
});
50+
51+
//GET Request
52+
const response = await client.invoker.invoke(SERVICE_TO_INVOKE, METHOD_TO_INVOKE, HttpMethod.GET);
53+
}
54+
```
55+
- For a full guide on service invocation visit [How-To: Invoke a service]({{< ref howto-invoke-discover-services.md >}}).
56+
57+
### Save & get application state
58+
59+
```javascript
60+
import { DaprClient } from "@roadwork/dapr-js-sdk/http";
61+
62+
const daprHost = "127.0.0.1";
63+
const daprPort = "50050";
64+
65+
async function start() {
66+
const client = new DaprClient(daprHost, daprPort);
67+
68+
//Save state
69+
const response = await client.state.save(STATE_STORE_NAME, [
70+
{
71+
key: FIRST_KEY_NAME
72+
value: FIRST_VALUE
73+
},
74+
{
75+
key: SECOND_KEY_NAME,
76+
value: SECOND_VALUE
77+
},
78+
{
79+
key: THIRD_KEY_NAME
80+
value: THIRD_VALUE
81+
}
82+
]);
83+
84+
//Get State
85+
const response = await client.state.get(STATE_STORE_NAME, FIRST_KEY_NAME);
86+
87+
//Get Bulk State
88+
const response = await client.state.getBulk(STATE_STORE_NAME, [ FIRST_KEY_NAME, SECOND_KEY_NAME ]);
89+
90+
//Delete State
91+
const response = await client.state.delete(STATE_STORE_NAME, FIRST_KEY_NAME);
92+
}
93+
```
94+
- For a full list of state operations visit [How-To: Get & save state]({{< ref howto-get-save-state.md >}}).
95+
96+
### Publish & subscribe to messages
97+
98+
##### Publish messages
99+
100+
```javascript
101+
import { DaprClient } from "@roadwork/dapr-js-sdk/http";
102+
103+
const daprHost = "127.0.0.1";
104+
const daprPort = "50050";
105+
106+
async function start() {
107+
const client = new DaprClient(daprHost, daprPort);
108+
109+
const response = await client.pubsub.publish(PUBSUB_NAME, TOPIC_NAME, { messsage });
110+
}
111+
```
112+
113+
##### Subscribe to messages
114+
115+
```javascript
116+
import { DaprClient } from "@roadwork/dapr-js-sdk/http";
117+
118+
const daprHost = "127.0.0.1";
119+
const daprPort = "50050";
120+
121+
async function start() {
122+
const client = new DaprClient(daprHost, daprPort);
123+
124+
const response = await server.pubsub.subscribe(PUBSUB_NAME, TOPIC_NAME, async (data) => console.log(`Got Data: ${JSON.stringify(data)}`));
125+
}
126+
```
127+
128+
- For a full list of state operations visit [How-To: Publish & subscribe]({{< ref howto-publish-subscribe.md >}}).
129+
130+
### Interact with bindings
131+
132+
**Output Bindings**
133+
```javascript
134+
import { DaprClient } from "@roadwork/dapr-js-sdk/http";
135+
136+
const daprHost = "127.0.0.1";
137+
const daprPort = "50050";
138+
139+
async function start() {
140+
const client = new DaprClient(daprHost, daprPort);
141+
142+
const response = await client.binding.send(BINDING_NAME, BINDING_OPERATION, { message });
143+
}
144+
```
145+
146+
**Input Bindings**
147+
```javascript
148+
import { DaprServer } from "@roadwork/dapr-js-sdk/http";
149+
150+
const daprHost = "127.0.0.1";
151+
const daprPort = "50050";
152+
const daprInternalServerPort = "50051"; // App Port of this Example Server
153+
154+
async function start() {
155+
const server = new DaprServer(daprHost, daprPort, daprInternalServerPort);
156+
157+
const response = await server.binding.receive(BINDING_NAME, async (data) => console.log(`Got Data: ${JSON.stringify(data)}`));
158+
}
159+
```
160+
161+
- For a full guide on output bindings visit [How-To: Use bindings]({{< ref howto-bindings.md >}}).
162+
163+
### Retrieve secrets
164+
165+
```javascript
166+
import { DaprClient } from "@roadwork/dapr-js-sdk/http";
167+
168+
const daprHost = "127.0.0.1";
169+
const daprPort = "50050";
170+
171+
async function start() {
172+
const client = new DaprClient(daprHost, daprPort);
173+
174+
//Retrieve a single secret from secret store
175+
const response = await client.secret.get(SECRET_STORE_NAME, secretKey);
176+
177+
// Retrieve all secrets from secret store
178+
const response = await client.secret.getBulk(SECRET_STORE_NAME);
179+
}
180+
```
181+
182+
- For a full guide on secrets visit [How-To: Retrieve secrets]({{< ref howto-secrets.md >}}).
183+
184+
### Actors
185+
An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the [Virtual Actor pattern](https://www.microsoft.com/en-us/research/project/orleans-virtual-actors/), which provides a single-threaded programming model and where actors are garbage collected when not in use. With Dapr's implementaiton, you write your Dapr actors according to the Actor model, and Dapr leverages the scalability and reliability that the underlying platform provides.
186+
187+
```javascript
188+
```
189+
190+
- For a full guide on actors visit [How-To: Use virtual actors in Dapr]({{< ref howto-actors.md >}}).
191+
192+
## Related links
193+
- [JavaScript SDK examples](https://github.com/dapr/js-sdk/tree/master/examples)

0 commit comments

Comments
 (0)