Skip to content

Commit db86f1e

Browse files
NoahMaizelsNoahMaizels
committed
develop on swarm revision
1 parent c75cdfa commit db86f1e

File tree

1 file changed

+10
-148
lines changed

1 file changed

+10
-148
lines changed

‎docs/develop/introduction.md‎

Lines changed: 10 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -48,159 +48,21 @@ The [Swarm-CLI](/docs/bee/working-with-bee/swarm-cli) command line tool is the r
4848

4949
## How to Integrate with a dApp
5050

51-
Once you've got your Bee node up and running, then you can begin integrating it into your dApp.
51+
Once you've got your Bee node up and running, then you can begin integrating it into your dApp.
5252

53-
- **bee-js**: [`bee-js` is the official JavaScript SDK for Swarm](https://bee-js.ethswarm.org/docs/), and is the *recommended approach* for building Swarm integrated dApps.
53+
- **bee-js**: [`bee-js` is the official JavaScript SDK for Swarm](https://bee-js.ethswarm.org/docs/), and is the *recommended approach* for building Swarm integrated dApps. It supports both NodeJS and browser based APIs, making it easy to integrate with both frontend and backend applications.
5454

55-
- **Raw API**: If required, you may also directly interact with the Bee HTTP API. This approach is discouraged unless explicitly required.
55+
:::tip
56+
Refer to the next section "Template Applications." to learn about using `create-swarm-app` to generate basic project scaffolding which demonstrate specifically how to use `bee-js` to integrate Swarm into your application.
57+
:::
5658

57-
## Template Applications
58-
59-
The best way to begin understanding how everything works together is by exploring a working app. The [`create-swarm-app` tool](https://www.npmjs.com/package/create-swarm-app) allows you to rapidly generate a minimalistic working Swarm application.
60-
61-
As explained in the [bee-js docs](https://bee-js.ethswarm.org/docs/getting-started/#quickstart-with-create-swarm-app), the `create-swarm-app` tool allows you to specify options to generate a template app for your chosen development environment. The supported options include: `node`, `node-esm`, `node-ts` and `vite-tsx`.
62-
63-
### Swarm Integrated Back-end
64-
65-
When `create-swarm-app` is run using either of the `node`, `node-esm`, or `node-ts` options, the tool will output a simple script containing the basic scaffolding for a Swarm integrated back-end using the specified environment. The output scripts are examples of Swarm enabled code which runs alongside a Bee node on a traditional server, and allows for dynamic interaction with the Swarm.
66-
67-
```bash
68-
npm init swarm-app@latest my-dapp node-ts
69-
```
70-
71-
```bash
72-
> npx
73-
> create-swarm-app my-dapp node-ts
74-
75-
Project created
76-
77-
cd my-dapp
78-
npm install
79-
npm start
80-
```
81-
82-
Your project structure will look like:
83-
84-
```bash
85-
.
86-
├── package.json
87-
├── src
88-
│   ├── config.ts
89-
│   └── index.ts
90-
└── tsconfig.json
91-
```
92-
93-
The Bee node's API endpoint is specified in `config.ts`:
94-
95-
96-
```js
97-
export const BEE_HOST = 'http://localhost:1633'
98-
```
99-
100-
This is the default endpoint used in all Bee API requests, and which is used to initialized a Bee object when using the `bee-js` SDK.
101-
102-
Within `index.ts`, the API endpoint is used to initialize a Bee object using `bee-js`, which is then used to pay for storage on Swarm if needed, and then upload and download data from Swarm:
103-
104-
`index.ts`:
105-
106-
```js
107-
import { Bee } from '@ethersphere/bee-js'
108-
import { BEE_HOST } from './config'
109-
110-
main()
111-
112-
async function main() {
113-
const bee = new Bee(BEE_HOST)
114-
const batchId = await getOrCreatePostageBatch(bee)
115-
console.log('Batch ID', batchId.toString())
116-
const data = 'Hello, world! The current time is ' + new Date().toLocaleString()
117-
const uploadResult = await bee.uploadData(batchId, data)
118-
console.log('Swarm hash', uploadResult.reference.toHex())
119-
const downloadResult = await bee.downloadData(uploadResult.reference)
120-
console.log('Downloaded data:', downloadResult.toUtf8())
121-
}
59+
- **Raw API**: If required, you may also directly interact with the [Bee HTTP API](/api/). This approach is discouraged unless explicitly required for your use case.
12260

123-
async function getOrCreatePostageBatch(bee: Bee) {
124-
const batches = await bee.getPostageBatches()
125-
const usable = batches.find(x => x.usable)
126-
127-
if (usable) {
128-
return usable.batchID
129-
} else {
130-
return bee.createPostageBatch('500000000', 20)
131-
}
132-
}
133-
```
134-
135-
When `create-swarm-app` is used with either `node` and `node-esm` options, a similar basic script will be output for the selected development environment.
136-
137-
### Fully Swarm Hosted dApp
138-
139-
In contrast with the previous example, the `vite-tsx` option for `create-swarm-app` will output the basic scaffolding for a Swarm integrated static site which can be uploaded to Swarm directly - no servers needed!
140-
141-
```bash
142-
npm init swarm-app@latest my-dapp vite-tsx
143-
```
144-
145-
```bash
146-
> npx
147-
> create-swarm-app my-dapp vite-tsx
148-
149-
Project created
150-
151-
cd my-dapp
152-
npm install
153-
npm start
154-
```
155-
156-
The output files will have this structure:
157-
158-
```bash
159-
tree .
160-
.
161-
├── index.html
162-
├── package.json
163-
├── src
164-
│   ├── App.tsx
165-
│   ├── config.ts
166-
│   └── index.tsx
167-
└── tsconfig.json
168-
```
169-
170-
171-
After installing and starting the application, you will be first be greeted with a button that will purchase a new postage batch or select an existing one as needed.
172-
173-
![](/img/develop-on-swarm-00.jpg)
174-
175-
After a postage batch is selected, you will be greeted with an interface for uploading data:
176-
177-
![](/img/develop-on-swarm-01.jpg)
178-
179-
After selecting a file to upload, a reference hash to the file will be returned:
180-
181-
![](/img/develop-on-swarm-02.jpg)
182-
183-
Right now our application is running on localhost, and is only accessible locally. To make this application accessible for anyone on Swarm, all we need to do create a production build of our application using `vite build` and then upload it to the Swarm with `swarm-cli`.
184-
185-
```bash
186-
npm run build
187-
```
61+
## Template Applications
18862

189-
This will generate a production build in the `/dist` directory, which we can than use `swarm-cli` to upload:
63+
Once you've got your Bee node up and running and have installed all the pre-requisites and recommended tools mentioned above, now you're really ready to get started building.
19064

191-
```bash
192-
swarm-cli upload dist
193-
```
65+
The best way get started is with a simple template application to serve as an example. The [`create-swarm-app` tool](https://www.npmjs.com/package/create-swarm-app) allows you to rapidly generate simple starter templates for several different use cases, and serve a the perfect jumping off point for further learning.
19466

195-
`swarm-cli` will prompt us to select a postage batch, after which it will automatically detect that we are trying upload a website, complete the upload, and return a hash to us which can now be used by anyone with a Bee node to access our app:
67+
For more details on using `create-swarm-app`, and for a step-by-step explanation of the template apps it can output, refer to the [guides in the bee-js docs](https://bee-js.ethswarm.org/docs/getting-started/#quickstart-with-create-swarm-app).
19668

197-
```bash
198-
? Please select a stamp for this action
199-
4996787aee78da46b6e32d8141aee89ebb4f2ef3301bf04e0a399247fc414f27 550.296 MB
200-
Setting --index-document to index.html
201-
Swarm hash: 764b08bb0f9e82d4bdce951b1ded816bd0417e039828e4308d61ab3035ff60a2
202-
URL: http://localhost:1633/bzz/764b08bb0f9e82d4bdce951b1ded816bd0417e039828e4308d61ab3035ff60a2/
203-
Stamp ID: 4996787a
204-
Usage: 13%
205-
Capacity (immutable): 550.296 MB remaining out of 628.910 MB
206-
```

0 commit comments

Comments
 (0)