Skip to content

Commit 5f8739b

Browse files
mikhail-1e20mikhail-1e20
authored
feat(docs): README edited to represent the current JS Client API (#256)
1 parent 7979db8 commit 5f8739b

File tree

4 files changed

+158
-41
lines changed

4 files changed

+158
-41
lines changed

‎CONTRIBUTING.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
## Contribute Code
22

3-
You are welcome to contribute to Fluence.
3+
You are welcome to contribute to Fluence!
44

55
Things you need to know:
66

7-
1. You need to **agree to the Contributors License Agreement**. This is a common practice in all major Open Source projects. At the current moment we are unable to accept contributions made on behalf of a company. Only individual contributions will be accepted.
8-
2. **Not all proposed contributions can be accepted**. Some features may e.g. just fit a third-party add-on better. The contribution must fit the overall direction of Fluence and really improve it. The more effort you invest, the better you should clarify in advance whether the contribution fits: the best way would be to just open an issue to discuss the contribution you plan to make.
7+
1. You need to **agree to the [Contributor License Agreement](https://gist.github.com/fluencelabs-org/3f4cbb3cc14c1c0fb9ad99d8f7316ed7) (CLA)**. This is a common practice in all major Open Source projects. At the current moment, we are unable to accept contributions made on behalf of a company. Only individual contributions will be accepted.
8+
9+
2. **Not all proposed contributions can be accepted**. Some features may, e.g., just fit a third-party add-on better. The contribution must fit the overall direction of Fluence and really improve it. The more effort you invest, the better you should clarify in advance whether the contribution fits: the best way would be to just open an issue to discuss the contribution you plan to make.
910

1011
### Contributor License Agreement
1112

12-
When you contribute, you have to be aware that your contribution is covered by **Apache License 2.0**, but might relicensed under few other software licenses mentioned in the **Contributor License Agreement**.
13-
In particular you need to agree to the [Contributor License Agreement](https://gist.github.com/fluencelabs-org/3f4cbb3cc14c1c0fb9ad99d8f7316ed7). If you agree to its content, you simply have to click on the link posted by the CLA assistant as a comment to the pull request. Click it to check the CLA, then accept it on the following screen if you agree to it. CLA assistant will save this decision for upcoming contributions and will notify you if there is any change to the CLA in the meantime.
13+
When you contribute, you have to be aware that your contribution is covered by **[Apache License 2.0](./LICENSE)**, but might relicensed under few other software licenses mentioned in the **Contributor License Agreement**. In particular, you need to agree to the Contributor License Agreement. If you agree to its content, you simply have to click on the link posted by the CLA assistant as a comment to the pull request. Click it to check the CLA, then accept it on the following screen if you agree to it. The CLA assistant will save this decision for upcoming contributions and will notify you if there is any change to the CLA in the meantime.

‎DEVELOPING.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Setting up dev environment
2+
3+
JS Client uses pnpm to manage monorepo packages. See [pnpm.io](https://pnpm.io/installation) for installation instructions.
4+
5+
Install dependencies
6+
7+
```bash
8+
pnpm install
9+
```
10+
11+
Build all packages
12+
13+
```
14+
pnpm -r build
15+
```
16+
17+
# Running tests
18+
19+
Tests are split into unit and integration categories. By default integration tests require a locally running Fluence node with 4310 port open for ws connections. The dependency can be started with docker
20+
21+
```bash
22+
docker run --rm -e RUST_LOG="info" -p 1210:1210 -p 4310:4310 fluencelabs/fluence -t 1210 -w 4310 -k gKdiCSUr1TFGFEgu2t8Ch1XEUsrN5A2UfBLjSZvfci9SPR3NvZpACfcpPGC3eY4zma1pk7UvYv5zb1VjvPHwCjj
23+
```
24+
25+
To run all tests
26+
27+
```bash
28+
pnpm -r test
29+
```
30+
31+
To run only unit tests
32+
33+
```bash
34+
pnpm -r test:unit
35+
```
36+
37+
To run only integration tests
38+
39+
```bash
40+
pnpm -r test:integration
41+
```
42+
43+
# Repo structure:
44+
45+
TBD
46+
47+
# Architecture
48+
49+
TBD

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -198,4 +198,4 @@
198198
distributed under the License is distributed on an "AS IS" BASIS,
199199
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200200
See the License for the specific language governing permissions and
201-
limitations under the License.
201+
limitations under the License.

‎README.md

+103-35
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,127 @@
1-
# Fluence JS
1+
# Fluence JS Client
22

3-
[![npm](https://img.shields.io/npm/v/@fluencelabs/fluence)](https://www.npmjs.com/package/@fluencelabs/fluence)
3+
[![npm](https://img.shields.io/npm/v/@fluencelabs/js-client.api?label=@fluencelabs/js-client.api)](https://www.npmjs.com/package/@fluencelabs/js-client.api)
4+
[![npm](https://img.shields.io/npm/v/@fluencelabs/js-client.web.standalone?label=@fluencelabs/js-client.web.standalone)](https://www.npmjs.com/package/@fluencelabs/js-client.web.standalone)
45

5-
Official TypeScript implementation of the Fluence Peer.
6+
This is the Javascript client for the [Fluence](https://fluence.network) network.
67

7-
## Getting started
88

9-
To start developing applications with Fluence JS refer to the official [documentation](https://fluence.dev/docs/build/fluence-js/)
9+
## Get Started
1010

11-
## Contributing
11+
Adding the Fluence JS client for your web application is very easy:
12+
13+
1. Add a script tag with the JS Client bundle to your `index.html`. The easiest way to do this is using a CDN (like [JSDELIVR](https://www.jsdelivr.com/) or [UNPKG](https://unpkg.com/)). The script is large, thus we highly recommend to use the `async` attribute.
14+
15+
Here is an example using the JSDELIVR CDN:
16+
17+
```html
18+
<head>
19+
<title>Cool App</title>
20+
<script src='https://cdn.jsdelivr.net/npm/@fluencelabs/[email protected]/dist/js-client.min.js'
21+
async></script>
22+
</head>
23+
```
24+
25+
If you cannot or don't want to use a CDN, feel free to get the script directly from the `npm` package and host in yourself: `https://www.npmjs.com/package/@fluencelabs/js-client.web.standalone`. You can find the script in the `/dist` directory of the package. (Note: this option means that developers understand what they are doing and know how to serve this file from their own web server.)
26+
27+
2. Install the following packages:
28+
29+
```
30+
npm i @fluencelabs/js-client.api @fluencelabs/fluence-network-environment
31+
```
32+
33+
3. Add the following lines at the beginning of your code:
34+
35+
```
36+
import { Fluence } from "@fluencelabs/js-client.api";
37+
import { krasnodar } from "@fluencelabs/fluence-network-environment";
38+
39+
Fluence.start({
40+
relay: krasnodar[3],
41+
});
42+
```
43+
44+
## Use Aqua in a Web Application
1245

13-
While the project is still in the early stages of development, you are welcome to track progress and contribute. As the project is undergoing rapid changes, interested contributors should contact the team before embarking on larger pieces of work. All contributors should consult with and agree to our [basic contributing rules](CONTRIBUTING.md).
46+
Once you've added the client, you can compile [Aqua](https://github.com/fluencelabs/aqua) and run it in your application. To compile Aqua, use [Fluence CLI](https://github.com/fluencelabs/fluence-cli).
1447

15-
### Setting up dev environment
48+
1. Install the package:
1649

17-
Fluence JS uses pnpm to manage monorepo packages. See [pnpm.io](https://pnpm.io/installation) for installation instructions.
50+
```
51+
npm i -D "@fluencelabs/fluence-cli"
52+
```
1853

19-
Install dependencies
54+
2. Add a directory in your project for Aqua code, e.g., `_aqua`.
2055

21-
```bash
22-
pnpm install
23-
```
56+
3. Put `*.aqua` files in that directory.
2457

25-
Build all packages
58+
4. Add a directory for compiled Aqua files inside you sources. For example, if your app source is located in the `src` directory, you can create `src/_aqua`.
2659

27-
```
28-
pnpm -r build
29-
```
60+
5. To compile Aqua code once, run `npx fluence aqua -i ./_aqua -o ./src/_aqua/`. To watch the changes and to recompile on the fly, add the `-w` flag: `npx fluence aqua -w -i ./_aqua -o ./src/_aqua/`.
3061

31-
### Running tests
62+
**A hint**: it might be a good idea to add these scripts to your `package.json` file.
63+
For example, you project structure could look like this:
3264

33-
Tests are split into unit and integration categories. By default integration tests require a locally running Fluence node with 4310 port open for ws connections. The dependency can be started with docker
65+
```
66+
┣ _aqua
67+
┃ ┗ demo.aqua
68+
┣ src
69+
┃ ┣ _aqua
70+
┃ ┃ ┗ demo.ts
71+
┃ ┗ index.ts
72+
┣ package-lock.json
73+
┣ package.json
74+
┗ tsconfig.json
75+
```
3476

35-
```bash
36-
docker run --rm -e RUST_LOG="info" -p 1210:1210 -p 4310:4310 fluencelabs/fluence -t 1210 -w 4310 -k gKdiCSUr1TFGFEgu2t8Ch1XEUsrN5A2UfBLjSZvfci9SPR3NvZpACfcpPGC3eY4zma1pk7UvYv5zb1VjvPHwCjj
37-
```
77+
Then, your `package.json` file should include the following lines:
3878

39-
To run all tests
79+
```
80+
{
81+
...
82+
"scripts": {
83+
...
84+
"aqua:compile": "fluence aqua -i ./aqua/ -o ./src/_aqua",
85+
"aqua:watch": "fluence aqua -w -i ./aqua/ -o ./src/_aqua"
86+
},
87+
...
88+
}
89+
```
4090

41-
```bash
42-
pnpm -r test
43-
```
91+
6. Now you can import and call Aqua code from your application like
92+
this:
4493

45-
To run only unit tests
94+
```
95+
import { getRelayTime } from "./_aqua/demo";
4696

47-
```bash
48-
pnpm -r test:unit
49-
```
97+
async function buttonClick() {
98+
const time = await getRelayTime();
99+
alert("relay time: " + time);
100+
}
101+
```
50102

51-
To run only integration tests
103+
**Warning**: Fluence JS client for Node.js is currently broken. We will fix this shortly.
104+
105+
106+
## Development
107+
108+
To hack on the Fluence JS Client itself, please refer to the [development page](./DEVELOPING.md).
109+
110+
111+
## Documentation
112+
113+
The starting point for all documentation related to Fluence is
114+
[fluence.dev](https://fluence.dev/). We also have an active [YouTube channel](https://www.youtube.com/@fluencelabs).
115+
116+
117+
## Support
118+
119+
Please, file an [issue](https://github.com/fluencelabs/fluence-js/issues) if you find a bug. You can also contact us at [Discord](https://discord.com/invite/5qSnPZKh7u) or [Telegram](https://t.me/fluence_project). We will do our best to resolve the issue ASAP.
120+
121+
## Contributing
52122

53-
```bash
54-
pnpm -r test:integration
55-
```
123+
Any interested person is welcome to contribute to the project. Please, make sure you read and follow some basic [rules](./CONTRIBUTING.md).
56124

57125
## License
58126

59-
[Apache 2.0](LICENSE)
127+
All software code is copyright (c) Fluence Labs, Inc. under the [Apache-2.0](./LICENSE) license.

0 commit comments

Comments
 (0)