# Development

## Principles

The Javascript SDK wraps the æternity API exposed by[Node's Swagger file](https://github.com/aeternity/aeternity/blob/master/config/swagger.yaml). It aims to abstract the API, while still providing\
low-level access to it's endpoints, when necessary.

It uses the following Javascript technologies and principles:

* [JavaScript the Good Parts](https://github.com/dwyl/Javascript-the-Good-Parts-notes) (because Crockford is always right)
* [ES6 modules](https://hacks.mozilla.org/2015/08/es6-in-depth-modules/), using `export` and `import`
* [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) using ES7 [async/await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) syntax, where applicable
* Statelessness wherever possible
* [webpack](https://webpack.js.org/) and the [Babel](https://babeljs.io/) [loader](https://github.com/babel/babel-loader)
* Loose coupling of modules to enable [tree-shaking](https://webpack.js.org/guides/tree-shaking/)
* Convention over configuration
* "Easy things should be easy, and hard things should be possible." [source](https://www.amazon.com/gp/feature.html?ie=UTF8\&docId=7137) -- [Larry Wall](https://en.wikipedia.org/wiki/Larry_Wall)
* Support for
  * module access, enabling tree-shaking
  * direct use in node scripts through bundling
  * direct use in browser `<script>` tags through bundling
  * bundling through webpack

## Requirements

aepp-sdk is transpiled to EcmaScript 5 through [WebPack](https://webpack.js.org/), using [Babel](https://babeljs.io/) and is expected to work in any sufficiently new version of [Node.js](https://nodejs.org/en/) or modern web browser.

## Contributing

1. Clone the application
2. Make sure your editor/IDE can read and use the `.editorconfig` file
3. Start hacking (and don't forget to add [test](#testing) for whatever you'll be building).

## Documenting

Apart from documenting features and code, there is also documentation automatically generated using [**TypeDoc**](https://typedoc.org/) for documenting TS files and [a script](https://github.com/aeternity/aepp-sdk-js/blob/1cd128798018d98bdd41eff9104442b44b385d46/tooling/docs/examples-to-md.js) for documenting examples and code partials.

```bash
#generate examples and api documentation
npm run docs:examples && npm run docs:api
```

## Building

aepp-sdk is built using npm. In order to build a production version, launch the `build` command.

```bash
npm install
npm run build
```

**Note**: If you experience errors during the building, you might need to install build tools for your OS.

**Windows: Windows Build Tools**

```bash
npm install -g windows-build-tools
```

**Ubuntu / Debian: Build Essential**

```bash
sudo apt-get update
sudo apt-get install build-essential
```

**Mac**

Download [Xcode](https://apps.apple.com/de/app/xcode/id497799835?mt=12) from AppStore, then run

```
xcode-select --install
```

## Generate bundle report

```bash
npx webpack --env REPORT
```

## Testing

To test, launch the `test` command. This will run [mocha](https://mochajs.org/)'s tests locally.

```bash
npm test
```

This repository also includes a docker-compose file, to allow you to **run your own æternity node locally**. If you want to do so, **from the root of the project**:

1. Run `docker-compose up node`
2. Congrats! you're now running your own æternity node locally.

The WebPack compilation provides two different build artifacts in `dist/`, one\
for Node.js and one for browsers. When referencing aepp-sdk through any modern\
build tooling, it should pick the right one automatically through the entry\
points defined in `package.json`.

## Installation / Linking

In order to add a local development version of aepp-sdk to a project, `npm link`[1](https://docs.npmjs.com/cli/link) can be used.

## Releasing

[How to release a new version](https://docs.aeternity.com/developer-documentation/aepp-sdk-js/docs/contrib/releases)