Skip to content

Commit 578a554

Browse files
chaseflemingchasefleming
authored
Update FCL docs (#1160)
* Update FCL doc * Fix links * Fix link --------- Co-authored-by: Chase Fleming <[email protected]>
1 parent 8dfc35a commit 578a554

File tree

1 file changed

+76
-66
lines changed

1 file changed

+76
-66
lines changed

‎docs/tools/clients/fcl-js/index.md

+76-66
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,26 @@ sidebar_position: 3
44

55
# Flow Client Library (FCL)
66

7-
The Flow Client Library (FCL) JS is a package used to interact with user wallets and the Flow blockchain. When using FCL for authentication, dapps are able to support all FCL-compatible wallets on Flow and their users without any custom integrations or changes needed to the dapp code.
7+
## 🌟 What is FCL?
88

9-
It was created to make developing applications that connect to the Flow blockchain easy and secure. It defines a standardized set of communication patterns between wallets, applications, and users that is used to perform a wide variety of actions for your dapp. FCL also offers a full featured SDK and utilities to interact with the Flow blockchain.
9+
The **Flow Client Library (FCL) JS** is a package designed to facilitate interactions between dapps, wallets, and the Flow blockchain. It provides a standardized way for applications to connect with users and their wallets, **eliminating the need for custom integrations**.
1010

11-
While FCL itself is a concept and standard, FCL JS is the javascript implementation of FCL and can be used in both browser and server environments. All functionality for connecting and communicating with wallet providers is restricted to the browser. We also have FCL Swift implementation for iOS, see [FCL Swift](https://github.com/zed-io/fcl-swift) contributed by [@lmcmz](https://github.com/lmcmz).
11+
### 🔑 Key Features:
12+
- 🔌 **Universal Wallet Support** – Works seamlessly with all FCL-compatible wallets, making authentication simple.
13+
- 🔐 **Secure Authentication** – Standardized authentication flow ensures a smooth user experience.
14+
- ⚡ **Blockchain Interactions** – Enables querying, mutating, and interacting with smart contracts on Flow.
15+
- 🛠️ **Full-Featured Utilities** – Offers built-in functions to streamline blockchain development.
16+
- 🌍 **Flexible Environment** – Can run in both browser and server environments, though wallet interactions are browser-only.
1217

13-
---
18+
FCL was created to make building Flow-connected applications **easy, secure, and scalable** by defining **standardized communication patterns** between wallets, applications, and users.
19+
20+
For iOS, we also offer [FCL Swift](https://github.com/Outblock/fcl-swift).
1421

22+
---
1523
## Getting Started
1624

1725
### Requirements
18-
19-
- Node version `v12.0.0 or higher`.
26+
- Node version `v12.0.0 or higher`.
2027

2128
### Installation
2229

@@ -29,156 +36,159 @@ npm i -S @onflow/fcl
2936
```shell
3037
yarn add @onflow/fcl
3138
```
32-
3339
#### Importing
3440

3541
**ES6**
36-
3742
```js
38-
import * as fcl from '@onflow/fcl';
43+
import * as fcl from "@onflow/fcl";
3944
```
40-
4145
**Node.js**
42-
4346
```js
44-
const fcl = require('@onflow/fcl');
47+
const fcl = require("@onflow/fcl");
4548
```
46-
4749
---
48-
4950
## FCL for Dapps
50-
5151
#### Wallet Interactions
5252

53-
- _Wallet Discovery_ and _Sign-up/Login_: Onboard users with ease. Never worry about supporting multiple wallets.
54-
Authenticate users with any [FCL compatible wallet](./index.md#current-wallet-providers).
55-
53+
- *Wallet Discovery* and *Sign-up/Login*: Onboard users with ease. Never worry about supporting multiple wallets.
54+
Authenticate users with any [FCL compatible wallet](#current-wallet-providers).
5655
```js
5756
// in the browser
58-
import * as fcl from '@onflow/fcl';
57+
import * as fcl from "@onflow/fcl"
5958

6059
fcl.config({
61-
'discovery.wallet': 'https://fcl-discovery.onflow.org/testnet/authn', // Endpoint set to Testnet
62-
});
60+
"discovery.wallet": "https://fcl-discovery.onflow.org/testnet/authn", // Endpoint set to Testnet
61+
})
6362

64-
fcl.authenticate();
63+
fcl.authenticate()
6564
```
66-
6765
![FCL Default Discovery UI](images/discovery.png)
6866

69-
> **Note**: A [Dapper Wallet](https://meetdapper.com/developers) developer account is required. To enable Dapper Wallet inside FCL, you need to [follow this guide](https://docs.meetdapper.com/quickstart).
67+
> **Note**: A [Dapper Wallet](https://meetdapper.com/developers) developer account is required. To enable Dapper Wallet inside FCL, you need to [follow this guide](https://docs.meetdapper.com/get-started).
7068
71-
- _Interact with smart contracts_: Authorize transactions via the user's chosen wallet
72-
- _Prove ownership of a wallet address_: Signing and verifying user signed data
69+
- *Interact with smart contracts*: Authorize transactions via the user's chosen wallet
70+
- *Prove ownership of a wallet address*: Signing and verifying user signed data
7371

74-
[Learn more about wallet interactions >](./api.md#wallet-interactions)
72+
[Learn more about wallet interactions >](api.md#wallet-interactions)
7573

7674
#### Blockchain Interactions
77-
78-
- _Query the chain_: Send arbitrary Cadence scripts to the chain and receive back decoded values
79-
75+
- *Query the chain*: Send arbitrary Cadence scripts to the chain and receive back decoded values
8076
```js
81-
import * as fcl from '@onflow/fcl';
77+
import * as fcl from "@onflow/fcl";
8278

8379
const result = await fcl.query({
8480
cadence: `
85-
access(all) fun main(a: Int, b: Int, addr: Address): Int {
81+
pub fun main(a: Int, b: Int, addr: Address): Int {
8682
log(addr)
8783
return a + b
8884
}
8985
`,
9086
args: (arg, t) => [
9187
arg(7, t.Int), // a: Int
9288
arg(6, t.Int), // b: Int
93-
arg('0xba1132bc08f82fe2', t.Address), // addr: Address
89+
arg("0xba1132bc08f82fe2", t.Address), // addr: Address
9490
],
9591
});
9692
console.log(result); // 13
9793
```
98-
99-
- _Mutate the chain_: Send arbitrary transactions with your own signatures or via a user's wallet to perform state changes on chain.
100-
94+
- *Mutate the chain*: Send arbitrary transactions with your own signatures or via a user's wallet to perform state changes on chain.
10195
```js
102-
import * as fcl from '@onflow/fcl';
96+
import * as fcl from "@onflow/fcl";
10397
// in the browser, FCL will automatically connect to the user's wallet to request signatures to run the transaction
10498
const txId = await fcl.mutate({
10599
cadence: `
106100
import Profile from 0xba1132bc08f82fe2
107101
108102
transaction(name: String) {
109-
prepare(account: auth(BorrowValue) &Account) {
110-
account.storage.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)
103+
prepare(account: AuthAccount) {
104+
account.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)
111105
}
112106
}
113107
`,
114-
args: (arg, t) => [arg('myName', t.String)],
108+
args: (arg, t) => [arg("myName", t.String)],
115109
});
116110
```
117111

118-
[Learn more about on-chain interactions >](./api.md#on-chain-interactions)
112+
[Learn more about on-chain interactions >](api.md#on-chain-interactions)
119113

120114
#### Utilities
121-
122115
- Get account details from any Flow address
123116
- Get the latest block
124117
- Transaction status polling
125118
- Event polling
126119
- Custom authorization functions
127120

128-
[Learn more about utilities >](./api.md#pre-built-interactions)
121+
[Learn more about utilities >](api.md#pre-built-interactions)
129122

130-
## Next Steps
123+
## Typescript Support
131124

132-
See the [Flow App Quick Start](../../../build/getting-started/fcl-quickstart.md).
125+
FCL JS supports TypeScript. If you need to import specific types, you can do so via the [@onflow/typedefs](https://github.com/onflow/fcl-js/tree/master/packages/typedefs) package.
133126

134-
See the full [API Reference](./api.md) for all FCL functionality.
127+
```typescript
128+
import {CurrentUser} from "@onflow/typedefs"
135129

136-
Learn Flow's smart contract language to build any script or transactions: [Cadence](https://cadence-lang.org/docs).
130+
const newUser: CurrentUser = {
131+
addr: null,
132+
cid: null,
133+
expiresAt: null,
134+
f_type: 'User',
135+
f_vsn: '1.0.0',
136+
loggedIn: null,
137+
services: []
138+
}
139+
```
137140

138-
Explore all of Flow [docs and tools](/).
141+
For all type definitions available, see [this file](https://github.com/onflow/fcl-js/blob/master/packages/typedefs/src/index.ts)
139142

140-
---
143+
## Next Steps
141144

142-
## FCL for Wallet Providers
145+
- See the [Flow App Quick Start](../../../build/getting-started/fcl-quickstart.md).
146+
- See the full [API Reference](api.md) for all FCL functionality.
147+
- Learn Flow's smart contract language to build any script or transactions: [Cadence](https://cadence-lang.org).
148+
- Explore all of Flow [docs and tools](https://developers.flow.com).
143149

150+
---
151+
## FCL for Wallet Providers
144152
Wallet providers on Flow have the flexibility to build their user interactions and UI through a variety of ways:
145-
146153
- Front channel communication via Iframe, pop-up, tab, or extension
147154
- Back channel communication via HTTP
148155

149-
FCL is agnostic to the communication channel and is configured to create both custodial and non-custodial wallets. This enables users to interact with wallet providers without needing to download an app or extension.
156+
FCL is agnostic to the communication channel and be configured to create both custodial and non-custodial wallets. This enables users to interact with wallet providers without needing to download an app or extension.
150157

151-
The communication channels involve responding to a set of pre-defined FCL messages to deliver the requested information to the dapp. Implementing a FCL compatible wallet on Flow is as simple as filling in the responses with the appropriate data when FCL requests them. If using any of the front-channel communication methods, FCL also provides a set of [wallet utilities](https://github.com/onflow/fcl-js/blob/master/packages/fcl/src/wallet-utils/index.js) to simplify this process.
158+
The communication channels involve responding to a set of pre-defined FCL messages to deliver the requested information to the dapp. Implementing a FCL compatible wallet on Flow is as simple as filling in the responses with the appropriate data when FCL requests them. If using any of the front-channel communication methods, FCL also provides a set of [wallet utilities](https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-utils/index.js) to simplify this process.
152159

153160
### Current Wallet Providers
154-
155161
- [Flow Wallet](https://wallet.flow.com/)
156-
- [Dapper Wallet](https://www.meetdapper.com/)
162+
- [NuFi Wallet](https://nu.fi/)
157163
- [Blocto](https://blocto.portto.io/en/)
158-
- [NuFi](https://nu.fi)
159164
- [Ledger](https://ledger.com) (limited transaction support)
165+
- [Dapper Wallet](https://www.meetdapper.com/) (beta access - general availability coming soon)
160166

161167
### Wallet Discovery
162-
163-
It can be difficult to get users to discover new wallets on a chain. To solve this, we created a wallet discovery service that can be configured and accessed through FCL to display all available Flow wallet providers to the user. This means:
164-
168+
It can be difficult to get users to discover new wallets on a chain. To solve this, we created a [wallet discovery service](https://github.com/onflow/fcl-discovery) that can be configured and accessed through FCL to display all available Flow wallet providers to the user. This means:
165169
- Dapps can display and support all FCL compatible wallets that launch on Flow without needing to change any code
166170
- Users don't need to sign up for new wallets - they can carry over their existing one to any dapp that uses FCL for authentication and authorization.
167171

168-
The discovery feature can be used via API, allowing you to customize your own UI or use the default UI without any additional configuration.
172+
The discovery feature can be used via API allowing you to customize your own UI or you can use the default UI without any additional configuration.
173+
174+
> Note: To get your wallet added to the discovery service, make a PR in [fcl-discovery](https://github.com/onflow/fcl-discovery).
169175
170176
### Building a FCL compatible wallet
171177

172-
- Read the [wallet guide](https://github.com/onflow/fcl-js/blob/master/packages/fcl/src/wallet-provider-spec/draft-v3.md) to understand the implementation details.
173-
- Review the architecture of the [Flow Dev Wallet](https://github.com/onflow/fcl-dev-wallet) for an overview.
178+
- Read the [wallet guide](https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-provider-spec/draft-v4.md) to understand the implementation details.
179+
- Review the architecture of the [FCL dev wallet](https://github.com/onflow/fcl-dev-wallet) for an overview.
174180
- If building a non-custodial wallet, see the [Account API](https://github.com/onflow/flow-account-api) and the [FLIP](https://github.com/onflow/flow/pull/727) on derivation paths and key generation.
175181

176182
---
177183

178-
## Support
184+
## 🛠 Want to Use the Flow SDK Directly?
179185

180-
Notice an problem or want to request a feature? [Add an issue](https://github.com/onflow/fcl-js/issues).
186+
If you prefer to interact with Flow at a **lower level** without using FCL, you can use the [Flow JavaScript SDK](sdk-guidelines.md) directly. The SDK provides raw access to Flow's API for sending transactions, executing scripts, and managing accounts.
181187

182-
Discuss FCL with the community on the [forum](https://forum.onflow.org/c/developer-tools/flow-fcl/22).
188+
FCL is built **on top of the Flow SDK**, making it easier to handle authentication, wallet interactions, and dapp connectivity. Choose the approach that best fits your use case.
189+
190+
## Support
183191

184-
Join the Flow community on [Discord](https://discord.gg/flow) to keep up to date and to talk to the team.
192+
- Notice a problem or want to request a feature? [Add an issue](https://github.com/onflow/fcl-js/issues).
193+
- Join the Flow community on [Discord](https://discord.gg/flow) to keep up to date and to talk to the team.
194+
- Read the [Contributing Guide](https://github.com/onflow/fcl-js/blob/master/CONTRIBUTING.md) to learn how to contribute to the project.

0 commit comments

Comments
 (0)