mirror of
https://github.com/fluencelabs/examples
synced 2024-12-04 03:00:18 +00:00
feat: Update readme files for JS Client examples (#430)
This commit is contained in:
Pavel
GitHub
parent
3678e46b66
commit
9e5e485e0a
@ -4,6 +4,12 @@ This sample project demonstrates how fluence network can be accessed from the br
|
||||
|
||||
## Getting started
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
npm i
|
||||
```
|
||||
|
||||
Run aqua compiler in watch mode:
|
||||
|
||||
```bash
|
||||
@ -18,130 +24,6 @@ npm start
|
||||
|
||||
The browser window with `localhost:3000` should open
|
||||
|
||||
## How it works
|
||||
|
||||
The application can be split into two main building blocks: the runtime provided by the `@fluencelabs/fluence` package and the compiler for the `Aqua` language. The workflow is as follows:
|
||||
|
||||
1. You write aqua code
|
||||
2. Aqua gets compiled into the typescript file
|
||||
3. The typescript is build by the webpack (or any other tool of you choice) into js bunlde.
|
||||
|
||||
## Project structure
|
||||
|
||||
```
|
||||
aqua (1)
|
||||
┗ getting-started.aqua (3)
|
||||
node_modules
|
||||
public
|
||||
src
|
||||
┣ _aqua (2)
|
||||
┃ ┗ getting-started.ts (4)
|
||||
┣ App.scss
|
||||
┣ App.tsx
|
||||
┣ index.css
|
||||
┣ index.tsx
|
||||
┣ logo.svg
|
||||
┗ react-app-env.d.ts
|
||||
package-lock.json
|
||||
package.json
|
||||
tsconfig.json
|
||||
```
|
||||
|
||||
The project structure is based on the create-react-app template with some minor differences:
|
||||
|
||||
* `aqua` (1) contains the Aqua source code files. The complier picks them up and generate corresponding typescript file. See `getting-started.aqua` (3) and `getting-started.ts` respectively
|
||||
* `src/_aqua` (2) is where the generated target files are places. The target directory is conveniently placed inside the sources directory which makes it easy to import typescript functions from the application source code
|
||||
|
||||
## npm packages and scripts
|
||||
|
||||
The following npm packages are used:
|
||||
|
||||
* `@fluencelabs/fluence` - is the client for Fluence Network running inside the browser. See https://github.com/fluencelabs/fluence-js for additional information
|
||||
* `@fluencelabs/fluence-network-environment` - is the maintained list of Fluence networks and nodes to connect to.
|
||||
* `@fluencelabs/aqua` - is the command line interface for Aqua compiler. See https://github.com/fluencelabs/aqua for more information
|
||||
* `@fluencelabs/aqua-lib` - Aqua language standard library
|
||||
* `chokidar-cli` - A tool to watch for aqua file changes and compile them on the fly
|
||||
|
||||
The compilation of aqua code is implemented with these scripts:
|
||||
|
||||
```
|
||||
scripts: {
|
||||
...
|
||||
"compile-aqua": "aqua -i ./aqua/ -o ./src/_aqua",
|
||||
"watch-aqua": "chokidar \"**/*.aqua\" -c \"npm run compile-aqua\""
|
||||
}
|
||||
...
|
||||
```
|
||||
|
||||
The interface is pretty straightforward: you just specify the input and output directories for the compiler.
|
||||
|
||||
## Aqua code
|
||||
|
||||
```
|
||||
import "@fluencelabs/aqua-lib/builtin.aqua"
|
||||
|
||||
func getRelayTime(relayPeerId: PeerId) -> u64: (1)
|
||||
on relayPeerId: (2)
|
||||
ts <- Peer.timestamp_ms() (3)
|
||||
<- ts (4)
|
||||
|
||||
```
|
||||
|
||||
The code above defines a function which retrieves the current timestamp from the relay node. The function works as following:
|
||||
|
||||
1. The function definition, specifying arguments and return value types
|
||||
2. Shift the execution to the peer with id equal to `relayPeerId`
|
||||
3. Calls built-in function on the current peer and stores the result into a variable
|
||||
4. Returns the result
|
||||
|
||||
The function gets compiled into typescript and can be called from the application code (see next section)
|
||||
|
||||
## Application code
|
||||
|
||||
Let's take a look at how we can use Fluence from typecript.
|
||||
|
||||
First, we need to import the relevant packages:
|
||||
|
||||
```typescript
|
||||
import { createClient, FluenceClient } from "@fluencelabs/fluence";
|
||||
import { krasnodar } from "@fluencelabs/fluence-network-environment";
|
||||
import { getRelayTime } from "./_aqua/getting-started";
|
||||
```
|
||||
|
||||
Please notice that the function defined in Aqua has been compiled into typescript and can be directly imported. Using the code generated by the compiler is as easy as calling a function. The compiler generates all the boilerplate needed to send a particle into the network and wraps it into a single call. Note that all the type information and therefore type checking and code completion facilities are there!
|
||||
|
||||
Next we initialize the client:
|
||||
|
||||
```typescript
|
||||
const relayNode = krasnodar[0];
|
||||
|
||||
function App() {
|
||||
const [client, setClient] = useState<FluenceClient | null>(null);
|
||||
|
||||
...
|
||||
|
||||
useEffect(() => {
|
||||
createClient(relayNode)
|
||||
.then((client) => setClient(client))
|
||||
.catch((err) => console.log("Client initialization failed", err));
|
||||
}, [client]);
|
||||
```
|
||||
|
||||
Every peer running in the browser must connect to the network through a relay node. We use the first node of the krasnodar network there. In our example we store the client using React `useState` facilities. Feel free to store wherever you store other application state.
|
||||
|
||||
Executing Aqua is as easy as calling a function in typesctipt:
|
||||
|
||||
```typescript
|
||||
const doGetRelayTime = async () => {
|
||||
if (!client) {
|
||||
return;
|
||||
}
|
||||
|
||||
const time = await getRelayTime(client, relayNode.peerId);
|
||||
setRelayTime(new Date(time));
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Learn more
|
||||
|
||||
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/js-client/js-client)
|
||||
|
||||
21
js-client-examples/hello-world/README.md
Normal file
21
js-client-examples/hello-world/README.md
Normal file
@ -0,0 +1,21 @@
|
||||
# Getting Started with Fluence
|
||||
|
||||
This is a minimalistic Node.js application for Fluence using Fluence JS Client.
|
||||
|
||||
## Getting started
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
npm i
|
||||
```
|
||||
|
||||
Run the Node.js application:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
## Learn more
|
||||
|
||||
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/js-client/js-client)
|
||||
29
js-client-examples/node-example/README.md
Normal file
29
js-client-examples/node-example/README.md
Normal file
@ -0,0 +1,29 @@
|
||||
# Getting Started with Fluence
|
||||
|
||||
This is a sample Node.js application using Fluence JS Client. It exposes a calculator service written in Typescript which can be accessed from Fluence Network using Aqua language
|
||||
|
||||
## Getting started
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
npm i
|
||||
```
|
||||
|
||||
Start the Node.js application:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
This should start listening to incoming particles from Fluence Network.
|
||||
|
||||
Try interacting with the application with some aqua:
|
||||
|
||||
```bash
|
||||
./run_calculation.sh
|
||||
```
|
||||
|
||||
## Learn more
|
||||
|
||||
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/js-client/js-client)
|
||||
10
quickstart/1-browser-to-browser/README.md
Normal file
10
quickstart/1-browser-to-browser/README.md
Normal file
@ -0,0 +1,10 @@
|
||||
# Getting started
|
||||
|
||||
```bash
|
||||
npm i
|
||||
npm start
|
||||
```
|
||||
|
||||
The browser window with `localhost:3000` should open
|
||||
|
||||
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/quick-start/browser-to-browser/)
|
||||
10
quickstart/3-browser-to-service/README.md
Normal file
10
quickstart/3-browser-to-service/README.md
Normal file
@ -0,0 +1,10 @@
|
||||
# Getting started
|
||||
|
||||
```bash
|
||||
npm i
|
||||
npm start
|
||||
```
|
||||
|
||||
The browser window with `localhost:3000` should open
|
||||
|
||||
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/quick-start/browser-to-service/)
|
||||
Loading…
Reference in New Issue
Block a user