From 5f8739b76d53f7e56bc429a32114ec7ff7450536 Mon Sep 17 00:00:00 2001 From: mikhail-1e20 <122285300+mikhail-1e20@users.noreply.github.com> Date: Thu, 16 Feb 2023 17:45:37 +0300 Subject: [PATCH] feat(docs): README edited to represent the current JS Client API (#256) --- CONTRIBUTING.md | 10 +-- DEVELOPING.md | 49 ++++++++++++++ LICENSE | 2 +- README.md | 166 ++++++++++++++++++++++++++++++++++-------------- 4 files changed, 172 insertions(+), 55 deletions(-) create mode 100644 DEVELOPING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e3b264d..b43bbe7a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,13 @@ ## Contribute Code -You are welcome to contribute to Fluence. +You are welcome to contribute to Fluence! Things you need to know: -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. -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. +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. + +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. ### Contributor License Agreement -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**. -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. +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. diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 00000000..e9022f4c --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,49 @@ +# Setting up dev environment + +JS Client uses pnpm to manage monorepo packages. See [pnpm.io](https://pnpm.io/installation) for installation instructions. + +Install dependencies + +```bash +pnpm install +``` + +Build all packages + +``` +pnpm -r build +``` + +# Running tests + +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 + +```bash + docker run --rm -e RUST_LOG="info" -p 1210:1210 -p 4310:4310 fluencelabs/fluence -t 1210 -w 4310 -k gKdiCSUr1TFGFEgu2t8Ch1XEUsrN5A2UfBLjSZvfci9SPR3NvZpACfcpPGC3eY4zma1pk7UvYv5zb1VjvPHwCjj +``` + +To run all tests + +```bash +pnpm -r test +``` + +To run only unit tests + +```bash +pnpm -r test:unit +``` + +To run only integration tests + +```bash +pnpm -r test:integration +``` + +# Repo structure: + +TBD + +# Architecture + +TBD diff --git a/LICENSE b/LICENSE index f49a4e16..261eeb9e 100644 --- a/LICENSE +++ b/LICENSE @@ -198,4 +198,4 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and - limitations under the License. \ No newline at end of file + limitations under the License. diff --git a/README.md b/README.md index 447b9077..ec825dd4 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,127 @@ -# Fluence JS +# Fluence JS Client -[![npm](https://img.shields.io/npm/v/@fluencelabs/fluence)](https://www.npmjs.com/package/@fluencelabs/fluence) +[![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) +[![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) -Official TypeScript implementation of the Fluence Peer. +This is the Javascript client for the [Fluence](https://fluence.network) network. -## Getting started -To start developing applications with Fluence JS refer to the official [documentation](https://fluence.dev/docs/build/fluence-js/) +## Get Started + +Adding the Fluence JS client for your web application is very easy: + +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. + + Here is an example using the JSDELIVR CDN: + + ```html + + Cool App + + + ``` + + 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.) + +2. Install the following packages: + + ``` + npm i @fluencelabs/js-client.api @fluencelabs/fluence-network-environment + ``` + +3. Add the following lines at the beginning of your code: + + ``` + import { Fluence } from "@fluencelabs/js-client.api"; + import { krasnodar } from "@fluencelabs/fluence-network-environment"; + + Fluence.start({ + relay: krasnodar[3], + }); + ``` + +## Use Aqua in a Web Application + +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). + +1. Install the package: + + ``` + npm i -D "@fluencelabs/fluence-cli" + ``` + +2. Add a directory in your project for Aqua code, e.g., `_aqua`. + +3. Put `*.aqua` files in that directory. + +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`. + +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/`. + + **A hint**: it might be a good idea to add these scripts to your `package.json` file. + For example, you project structure could look like this: + + ``` + ┣ _aqua + ┃ ┗ demo.aqua + ┣ src + ┃ ┣ _aqua + ┃ ┃ ┗ demo.ts + ┃ ┗ index.ts + ┣ package-lock.json + ┣ package.json + ┗ tsconfig.json + ``` + + Then, your `package.json` file should include the following lines: + + ``` + { + ... + "scripts": { + ... + "aqua:compile": "fluence aqua -i ./aqua/ -o ./src/_aqua", + "aqua:watch": "fluence aqua -w -i ./aqua/ -o ./src/_aqua" + }, + ... + } + ``` + +6. Now you can import and call Aqua code from your application like + this: + + ``` + import { getRelayTime } from "./_aqua/demo"; + + async function buttonClick() { + const time = await getRelayTime(); + alert("relay time: " + time); + } + ``` + +**Warning**: Fluence JS client for Node.js is currently broken. We will fix this shortly. + + +## Development + +To hack on the Fluence JS Client itself, please refer to the [development page](./DEVELOPING.md). + + +## Documentation + +The starting point for all documentation related to Fluence is +[fluence.dev](https://fluence.dev/). We also have an active [YouTube channel](https://www.youtube.com/@fluencelabs). + + +## Support + +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. ## Contributing -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). - -### Setting up dev environment - -Fluence JS uses pnpm to manage monorepo packages. See [pnpm.io](https://pnpm.io/installation) for installation instructions. - -Install dependencies - -```bash -pnpm install -``` - -Build all packages - -``` -pnpm -r build -``` - -### Running tests - -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 - -```bash - docker run --rm -e RUST_LOG="info" -p 1210:1210 -p 4310:4310 fluencelabs/fluence -t 1210 -w 4310 -k gKdiCSUr1TFGFEgu2t8Ch1XEUsrN5A2UfBLjSZvfci9SPR3NvZpACfcpPGC3eY4zma1pk7UvYv5zb1VjvPHwCjj -``` - -To run all tests - -```bash -pnpm -r test -``` - -To run only unit tests - -```bash -pnpm -r test:unit -``` - -To run only integration tests - -```bash -pnpm -r test:integration -``` +Any interested person is welcome to contribute to the project. Please, make sure you read and follow some basic [rules](./CONTRIBUTING.md). ## License -[Apache 2.0](LICENSE) +All software code is copyright (c) Fluence Labs, Inc. under the [Apache-2.0](./LICENSE) license.