Skip to content

Commit

Permalink
Update README to flow better (#907)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Shaptic
Shaptic authored Jan 10, 2024
1 parent 82d0dfb commit 547b360
Showing 1 changed file with 154 additions and 123 deletions.
277 changes: 154 additions & 123 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@

<div align="center">
<img alt="Stellar" src="https://github.com/stellar/.github/raw/master/stellar-logo.png" width="558" />
<br/>
Expand All @@ -15,160 +16,87 @@

js-stellar-sdk is a JavaScript library for communicating with a
[Stellar Horizon server](https://github.com/stellar/go/tree/master/services/horizon) and [Soroban RPC](https://soroban.stellar.org/docs/reference/rpc).
It is used for building Stellar apps either on Node.js or in the browser.
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.

It provides:

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

### stellar-sdk vs stellar-base

`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.

**Most people will want stellar-sdk instead of stellar-base.** You should only
use stellar-base if you know what you're doing!

If you add `stellar-sdk` to a project, **do not add `stellar-base`!** Mis-matching
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.
**Jump to:**

> **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).
> 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 `stellar-sdk`/`stellar-base` in a browser you can ignore
> this. However, for production backend deployments you should be
> using `sodium-native`. If `sodium-native` is successfully installed and working the
> `StellarSdk.FastSigning` variable will return `true`.
* [Installation](#installation): details on hitting the ground running
* [Usage](#usage): links to documentation and a variety of workarounds for non-traditional JavaScript environments
- [...with React Native](#usage-with-react-native)
- [...with Expo](#usage-with-expo-managed-workflows)
- [...with CloudFlare Workers](#usage-with-cloudflare-workers)
* [Developing](#developing): contribute to the project!
* [Understanding `stellar-sdk` vs. `stellar-base`](#stellar-sdk-vs-stellar-base)
* [License](#license)

## Quick start
## Installation

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

```shell
npm install --save @stellar/stellar-sdk
# or
yarn add @stellar/stellar-sdk
```

Alternatively, you can use cdnjs in a browser:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
````

## Install

### To use as a module in a Node.js project

1. Install it using npm:

```shell
npm install --save stellar-sdk
```

2. require/import it in your JavaScript:
Then, require or import it in your JavaScript code:

```js
var StellarSdk = require('@stellar/stellar-sdk');
// or
import * as StellarSdk from '@stellar/stellar-sdk';
```

### To self host for use in the browser

1. Install it using [bower](http://bower.io):
(Preferably, you would only import the pieces you need to enable tree-shaking and lower your final bundle sizes.)

```shell
bower install @stellar/stellar-sdk
```
### Browsers

2. Include it in the browser:
You can use a CDN:

```html
<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
<script>
console.log(StellarSdk);
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
```

If you don't want to use or install Bower, you can copy built JS files from the
[bower-js-stellar-sdk repo](https://github.com/stellar/bower-js-stellar-sdk).
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):

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

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

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
<script>
console.log(StellarSdk);
</script>
```

Note that this method relies using a third party to host the JS library. This
may not be entirely secure.

Make sure that you are using the latest version number. They can be found on the
[releases page in Github](https://github.com/stellar/js-stellar-sdk/releases).

### To develop and test js-stellar-sdk itself

1. Clone the repo:

```shell
git clone https://github.com/stellar/js-stellar-sdk.git
```

2. Install dependencies inside js-stellar-sdk folder:

```shell
cd js-stellar-sdk
yarn
```

3. Install Node 18

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.

Here's how to install `nvm` if you haven't: https://github.com/creationix/nvm

```shell
nvm install

# if you've never installed 16 before you'll want to re-install yarn
npm install -g yarn
```

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
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.

4. Observe the project's code style
| 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. |
|----|

While you're making changes, make sure to run the linter to catch any linting
errors (in addition to making sure your text editor supports ESLint)

```shell
yarn fmt
```
## Usage

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

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

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

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

### Usage with React-Native

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

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

#### Using in an Expo managed workflow
#### Usage with Expo managed workflows

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

```javascript
import * as Random from 'expo-random';
import StellarSdk from '@stellar/stellar-sdk';
import { Keypair } from '@stellar/stellar-sdk';

const generateRandomKeypair = () => {
const randomBytes = Random.getRandomBytes(32);

return StellarSdk.Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
return Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
};
```

## Testing
#### Usage with CloudFlare Workers

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.

It requires the following additional tweaks to your project:
* the `axios-fetch-adapter` lets you use `axios` with `fetch` as a backend, which is available to CF workers
* it only works with `axios@"<= 1.0.0"` versions, so we need to force an override into the underlying dependency
* and this can be problematic with newer `yarn` versions, so we need to force the environment to use Yarn 1

In summary, the `package.json` tweaks look something like this:

```jsonc
"dependencies": {
// ...
"@stellar/stellar-sdk": "git+https://github.com/stellar/js-stellar-sdk#make-eventsource-optional",
"@vespaiach/axios-fetch-adapter": "^0.3.1",
"axios": "^0.26.1"
},
"overrides": {
"@stellar/stellar-sdk": {
"axios": "$axios"
}
},
"packageManager": "[email protected]"
```

Then, you need to override the adapter in your codebase:

```typescript
import { Horizon } from '@stellar/stellar-sdk';
import fetchAdapter from '@vespaiach/axios-fetch-adapter';

Horizon.AxiosClient.defaults.adapter = fetchAdapter as any;

// then, the rest of your code...
```

All HTTP calls will use `fetch`, now, meaning it should work in the CloudFlare Worker environment.

## Developing

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.

1. Clone the repo:

```shell
git clone https://github.com/stellar/js-stellar-sdk.git
```

2. Install dependencies inside js-stellar-sdk folder:

```shell
cd js-stellar-sdk
yarn
```

3. Install Node 18

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.

Here's how to install `nvm` if you haven't: https://github.com/creationix/nvm

```shell
nvm install 18

# if you've never installed 18 before you'll want to re-install yarn
npm install -g yarn
```

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

4. Observe the project's code style

While you're making changes, make sure to run the linter to catch any linting
errors (in addition to making sure your text editor supports ESLint) and conform to the project's code style.

```shell
yarn fmt
```

### Building
You can build the developer version (unoptimized, commented, with source maps, etc.) or the production bundles:

```shell
yarn build
# or
yarn build:prod
```

### Testing

To run all tests:

Expand All @@ -229,13 +245,19 @@ To run a specific set of tests:
```shell
yarn test:node
yarn test:browser
yarn test:integration
```

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.

To generate and check the documentation site:

```shell
# install the `serve` command if you don't have it already
npm install -g serve
npm i -g serve

# clone the base library for complete docs
git clone https://github.com/stellar/js-stellar-base

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

## Documentation
### Publishing

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).

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

## Contributing and Publishing
### `stellar-sdk` vs `stellar-base`

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).
`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.

**Most people will want stellar-sdk instead of stellar-base.** You should only use stellar-base if you know what you're doing!

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.

> **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).
> 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`.
> If `sodium-native` is successfully installed and working the `StellarSdk.FastSigning` variable will return `true`.
## License
### License

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

0 comments on commit 547b360

Please sign in to comment.