Skip to content

Commit 547b360

Browse files
ShapticShaptic
authored
Update README to flow better (#907)
1 parent 82d0dfb commit 547b360

File tree

1 file changed

+154
-123
lines changed

1 file changed

+154
-123
lines changed

‎README.md‎

Lines changed: 154 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
12
<div align="center">
23
<img alt="Stellar" src="https://github.com/stellar/.github/raw/master/stellar-logo.png" width="558" />
34
<br/>
@@ -15,160 +16,87 @@
1516

1617
js-stellar-sdk is a JavaScript library for communicating with a
1718
[Stellar Horizon server](https://github.com/stellar/go/tree/master/services/horizon) and [Soroban RPC](https://soroban.stellar.org/docs/reference/rpc).
18-
It is used for building Stellar apps either on Node.js or in the browser.
19+
It is used for building Stellar apps either on Node.js or in the browser, though it can be used in other environments with some tinkering.
1920

2021
It provides:
2122

22-
- a networking layer API for Horizon endpoints (REST-based) and Soroban RPC (JSON-RPC-based).
23+
- a networking layer API for Horizon endpoints (REST-based),
24+
- a networking layer for Soroban RPC (JSONRPC-based).
2325
- facilities for building and signing transactions, for communicating with a
2426
Stellar Horizon instance, and for submitting transactions or querying network
2527
history.
2628

27-
### stellar-sdk vs stellar-base
28-
29-
`stellar-sdk` is a high-level library that serves as client-side API for Horizon and Soroban RPC, while [stellar-base](https://github.com/stellar/js-stellar-base) is lower-level library for creating Stellar primitive constructs via XDR helpers and wrappers.
30-
31-
**Most people will want stellar-sdk instead of stellar-base.** You should only
32-
use stellar-base if you know what you're doing!
33-
34-
If you add `stellar-sdk` to a project, **do not add `stellar-base`!** Mis-matching
35-
versions could cause weird, hard-to-find bugs. `stellar-sdk` automatically
36-
installs `stellar-base` and exposes all of its exports in case you need them.
29+
**Jump to:**
3730

38-
> **Important!** The Node.js version of the `stellar-base` (`stellar-sdk` dependency) package
39-
> uses the [`sodium-native`](https://www.npmjs.com/package/sodium-native) package as
40-
> an [optional dependency](https://docs.npmjs.com/files/package.json#optionaldependencies). `sodium-native` is
41-
> a low level binding to [libsodium](https://github.com/jedisct1/libsodium),
42-
> (an implementation of [Ed25519](https://ed25519.cr.yp.to/) signatures).
43-
> If installation of `sodium-native` fails, or it is unavailable, `stellar-base` (and `stellar-sdk`) will
44-
> fallback to using the [`tweetnacl`](https://www.npmjs.com/package/tweetnacl) package implementation.
45-
>
46-
> If you are using `stellar-sdk`/`stellar-base` in a browser you can ignore
47-
> this. However, for production backend deployments you should be
48-
> using `sodium-native`. If `sodium-native` is successfully installed and working the
49-
> `StellarSdk.FastSigning` variable will return `true`.
31+
* [Installation](#installation): details on hitting the ground running
32+
* [Usage](#usage): links to documentation and a variety of workarounds for non-traditional JavaScript environments
33+
- [...with React Native](#usage-with-react-native)
34+
- [...with Expo](#usage-with-expo-managed-workflows)
35+
- [...with CloudFlare Workers](#usage-with-cloudflare-workers)
36+
* [Developing](#developing): contribute to the project!
37+
* [Understanding `stellar-sdk` vs. `stellar-base`](#stellar-sdk-vs-stellar-base)
38+
* [License](#license)
5039

51-
## Quick start
40+
## Installation
5241

53-
Using npm to include js-stellar-sdk in your own project:
42+
Using npm or yarn to include `stellar-sdk` in your own project:
5443

5544
```shell
5645
npm install --save @stellar/stellar-sdk
46+
# or
47+
yarn add @stellar/stellar-sdk
5748
```
5849

59-
Alternatively, you can use cdnjs in a browser:
60-
61-
```html
62-
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
63-
````
64-
65-
## Install
66-
67-
### To use as a module in a Node.js project
68-
69-
1. Install it using npm:
70-
71-
```shell
72-
npm install --save stellar-sdk
73-
```
74-
75-
2. require/import it in your JavaScript:
50+
Then, require or import it in your JavaScript code:
7651

7752
```js
7853
var StellarSdk = require('@stellar/stellar-sdk');
7954
// or
8055
import * as StellarSdk from '@stellar/stellar-sdk';
8156
```
8257

83-
### To self host for use in the browser
84-
85-
1. Install it using [bower](http://bower.io):
58+
(Preferably, you would only import the pieces you need to enable tree-shaking and lower your final bundle sizes.)
8659

87-
```shell
88-
bower install @stellar/stellar-sdk
89-
```
60+
### Browsers
9061

91-
2. Include it in the browser:
62+
You can use a CDN:
9263

9364
```html
94-
<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
95-
<script>
96-
console.log(StellarSdk);
97-
</script>
65+
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
9866
```
9967

100-
If you don't want to use or install Bower, you can copy built JS files from the
101-
[bower-js-stellar-sdk repo](https://github.com/stellar/bower-js-stellar-sdk).
68+
Note that this method relies using a third party to host the JS library. This may not be entirely secure. You can self-host it via [Bower](http://bower.io):
10269

103-
### To use the [cdnjs](https://cdnjs.com/libraries/stellar-sdk) hosted script in the browser
70+
```shell
71+
bower install @stellar/stellar-sdk
72+
```
10473

105-
1. Instruct the browser to fetch the library from
106-
[cdnjs](https://cdnjs.com/libraries/stellar-sdk), a 3rd party service that
107-
hosts js libraries:
74+
and include it in the browser:
10875

10976
```html
110-
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
77+
<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
11178
<script>
11279
console.log(StellarSdk);
11380
</script>
11481
```
11582

116-
Note that this method relies using a third party to host the JS library. This
117-
may not be entirely secure.
118-
119-
Make sure that you are using the latest version number. They can be found on the
120-
[releases page in Github](https://github.com/stellar/js-stellar-sdk/releases).
121-
122-
### To develop and test js-stellar-sdk itself
123-
124-
1. Clone the repo:
125-
126-
```shell
127-
git clone https://github.com/stellar/js-stellar-sdk.git
128-
```
129-
130-
2. Install dependencies inside js-stellar-sdk folder:
131-
132-
```shell
133-
cd js-stellar-sdk
134-
yarn
135-
```
136-
137-
3. Install Node 18
138-
139-
Because we support the oldest maintenance version of Node, please install and develop on Node 18 so you don't get surprised when your code works locally but breaks in CI.
140-
141-
Here's how to install `nvm` if you haven't: https://github.com/creationix/nvm
142-
143-
```shell
144-
nvm install
145-
146-
# if you've never installed 16 before you'll want to re-install yarn
147-
npm install -g yarn
148-
```
149-
150-
If you work on several projects that use different Node versions, you might it
151-
helpful to install this automatic version manager:
152-
https://github.com/wbyoung/avn
83+
If you don't want to use or install Bower, you can copy the packaged JS files from the [Bower repo](https://github.com/stellar/bower-js-stellar-sdk), or just build the package yourself locally (see [Developing :arrow_right: Building](#building)) and copy the bundle.
15384

154-
4. Observe the project's code style
85+
| Always make sure that you are using the latest version number. They can be found on the [releases page](https://github.com/stellar/js-stellar-sdk/releases) in GitHub. |
86+
|----|
15587

156-
While you're making changes, make sure to run the linter to catch any linting
157-
errors (in addition to making sure your text editor supports ESLint)
158-
159-
```shell
160-
yarn fmt
161-
```
88+
## Usage
16289

90+
The usage documentation for this library lives in a handful of places:
16391

164-
## Usage
92+
* across the [Stellar Developer Docs](), which includes tutorials and examples,
93+
* within [this repository itself](https://github.com/stellar/js-stellar-sdk/blob/master/docs/reference/readme.md), and
94+
* on the generated [API doc site](https://stellar.github.io/js-stellar-sdk/).
16595

166-
For information on how to use js-stellar-sdk, take a look at [the
167-
documentation](https://stellar.github.io/js-stellar-sdk/), or [the
168-
examples](https://github.com/stellar/js-stellar-sdk/tree/master/docs/reference).
96+
You can also refer to:
16997

170-
There is also Horizon REST API Documentation
171-
[here](https://developers.stellar.org/api/introduction/) and Soroban JSON-RPC documentation [here](https://soroban.stellar.org/docs/reference/rpc).
98+
* the [documentation](https://developers.stellar.org/api/introduction/) for the Horizon REST API (if using the `Horizon` module) and
99+
* the [documentation](https://soroban.stellar.org/docs/reference/rpc) for Soroban RPC's API (if using the `SorobanRpc` module)
172100

173101
### Usage with React-Native
174102

@@ -192,7 +120,7 @@ module.exports = {
192120

193121
There is also a [sample](https://github.com/fnando/rn-stellar-sdk-sample) that you can follow.
194122

195-
#### Using in an Expo managed workflow
123+
#### Usage with Expo managed workflows
196124

197125
1. Install `yarn add --dev rn-nodeify`
198126
2. Add the following postinstall script:
@@ -207,16 +135,104 @@ At this point, the Stellar SDK will work, except that `StellarSdk.Keypair.random
207135

208136
```javascript
209137
import * as Random from 'expo-random';
210-
import StellarSdk from '@stellar/stellar-sdk';
138+
import { Keypair } from '@stellar/stellar-sdk';
211139

212140
const generateRandomKeypair = () => {
213141
const randomBytes = Random.getRandomBytes(32);
214-
215-
return StellarSdk.Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
142+
return Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
216143
};
217144
```
218145

219-
## Testing
146+
#### Usage with CloudFlare Workers
147+
148+
Both `eventsource` (needed for streaming) and `axios` (needed for making HTTP requests) are problematic dependencies in the CFW environment. The experimental branch [`make-eventsource-optional`](https://github.com/stellar/js-stellar-sdk/pull/901) is an attempt to resolve these issues.
149+
150+
It requires the following additional tweaks to your project:
151+
* the `axios-fetch-adapter` lets you use `axios` with `fetch` as a backend, which is available to CF workers
152+
* it only works with `axios@"<= 1.0.0"` versions, so we need to force an override into the underlying dependency
153+
* and this can be problematic with newer `yarn` versions, so we need to force the environment to use Yarn 1
154+
155+
In summary, the `package.json` tweaks look something like this:
156+
157+
```jsonc
158+
"dependencies": {
159+
// ...
160+
"@stellar/stellar-sdk": "git+https://github.com/stellar/js-stellar-sdk#make-eventsource-optional",
161+
"@vespaiach/axios-fetch-adapter": "^0.3.1",
162+
"axios": "^0.26.1"
163+
},
164+
"overrides": {
165+
"@stellar/stellar-sdk": {
166+
"axios": "$axios"
167+
}
168+
},
169+
"packageManager": "yarn@1.22.19"
170+
```
171+
172+
Then, you need to override the adapter in your codebase:
173+
174+
```typescript
175+
import { Horizon } from '@stellar/stellar-sdk';
176+
import fetchAdapter from '@vespaiach/axios-fetch-adapter';
177+
178+
Horizon.AxiosClient.defaults.adapter = fetchAdapter as any;
179+
180+
// then, the rest of your code...
181+
```
182+
183+
All HTTP calls will use `fetch`, now, meaning it should work in the CloudFlare Worker environment.
184+
185+
## Developing
186+
187+
So you want to contribute to the library: welcome! Whether you're working on a fork or want to make an upstream request, the dev-test loop is pretty straightforward.
188+
189+
1. Clone the repo:
190+
191+
```shell
192+
git clone https://github.com/stellar/js-stellar-sdk.git
193+
```
194+
195+
2. Install dependencies inside js-stellar-sdk folder:
196+
197+
```shell
198+
cd js-stellar-sdk
199+
yarn
200+
```
201+
202+
3. Install Node 18
203+
204+
Because we support the oldest maintenance version of Node, please install and develop on Node 18 so you don't get surprised when your code works locally but breaks in CI.
205+
206+
Here's how to install `nvm` if you haven't: https://github.com/creationix/nvm
207+
208+
```shell
209+
nvm install 18
210+
211+
# if you've never installed 18 before you'll want to re-install yarn
212+
npm install -g yarn
213+
```
214+
215+
If you work on several projects that use different Node versions, you might it helpful to install this automatic version manager: https://github.com/wbyoung/avn
216+
217+
4. Observe the project's code style
218+
219+
While you're making changes, make sure to run the linter to catch any linting
220+
errors (in addition to making sure your text editor supports ESLint) and conform to the project's code style.
221+
222+
```shell
223+
yarn fmt
224+
```
225+
226+
### Building
227+
You can build the developer version (unoptimized, commented, with source maps, etc.) or the production bundles:
228+
229+
```shell
230+
yarn build
231+
# or
232+
yarn build:prod
233+
```
234+
235+
### Testing
220236

221237
To run all tests:
222238

@@ -229,13 +245,19 @@ To run a specific set of tests:
229245
```shell
230246
yarn test:node
231247
yarn test:browser
248+
yarn test:integration
232249
```
233250

251+
In order to have a faster test loop, these suite-specific commands **do not** build the bundles first (unlike `yarn test`). If you make code changes, you will need to run `yarn build` (or a subset like `yarn build:node` corresponding to the test suite) before running the tests again to see your changes.
252+
234253
To generate and check the documentation site:
235254

236255
```shell
237256
# install the `serve` command if you don't have it already
238-
npm install -g serve
257+
npm i -g serve
258+
259+
# clone the base library for complete docs
260+
git clone https://github.com/stellar/js-stellar-base
239261

240262
# generate the docs files
241263
yarn docs
@@ -246,16 +268,25 @@ cd jsdoc && serve .
246268
# you'll be able to browse the docs at http://localhost:5000
247269
```
248270

249-
## Documentation
271+
### Publishing
272+
273+
For information on how to contribute or publish new versions of this software to `npm`, please refer to our [contribution guide](https://github.com/stellar/js-stellar-sdk/blob/master/CONTRIBUTING.md).
250274

251-
Documentation for this repo lives in
252-
[Developers site](https://github.com/stellar/js-stellar-sdk/blob/master/docs/reference/readme.md).
275+
## Miscellaneous
253276

254-
## Contributing and Publishing
277+
### `stellar-sdk` vs `stellar-base`
255278

256-
For information on how to contribute or publish new versions of this software to `npm`, please refer to our [contribution guide](https://github.com/stellar/js-stellar-sdk/blob/master/CONTRIBUTING.md).
279+
`stellar-sdk` is a high-level library that serves as client-side API for Horizon and Soroban RPC, while [`stellar-base](https://github.com/stellar/js-stellar-base) is lower-level library for creating Stellar primitive constructs via XDR helpers and wrappers.
280+
281+
**Most people will want stellar-sdk instead of stellar-base.** You should only use stellar-base if you know what you're doing!
282+
283+
If you add `stellar-sdk` to a project, **do not add `stellar-base`!** Mismatching versions could cause weird, hard-to-find bugs. `stellar-sdk` automatically installs `stellar-base` and exposes all of its exports in case you need them.
284+
285+
> **Important!** The Node.js version of the `stellar-base` (`stellar-sdk` dependency) package uses the [`sodium-native`](https://www.npmjs.com/package/sodium-native) package as an [optional dependency](https://docs.npmjs.com/files/package.json#optionaldependencies). `sodium-native` is a low level binding to [libsodium](https://github.com/jedisct1/libsodium), (an implementation of [Ed25519](https://ed25519.cr.yp.to/) signatures).
286+
> If installation of `sodium-native` fails, or it is unavailable, `stellar-base` (and `stellar-sdk`) will fallback to using the [`tweetnacl`](https://www.npmjs.com/package/tweetnacl) package implementation. If you are using them in a browser, you can ignore this. However, for production backend deployments, you should be using `sodium-native`.
287+
> If `sodium-native` is successfully installed and working the `StellarSdk.FastSigning` variable will return `true`.
257288
258-
## License
289+
### License
259290

260291
js-stellar-sdk is licensed under an Apache-2.0 license. See the
261292
[LICENSE](https://github.com/stellar/js-stellar-sdk/blob/master/LICENSE) file

0 commit comments

Comments
 (0)