examples/aqua-examples/getting-started-browser/README.md

# Getting Started with Fluence

This sample project demonstrates how fluence network can be accessed from the browser. As an example it retrieves the timestamp of the current time from the relay node. The project is based on an create-react-app template with slight modifications to integrate Fluence. The primary focus is the integration itself, i.e React could be swapped with a framework of your choice.

## Getting started

Run aqua compiler in watch mode:

```bash
npm run watch-aqua
```

Start the application

```bash
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));
  };
```