getting started page and template app revisions

docs/documentation/getting-started.md

@@ -8,12 +8,29 @@ import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
 
 
-
 ## About *bee-js* 
 
-`bee-js` simplifies development on Swarm by abstracting away many of finer details and quirks of the Bee API so that you can focus on building your dream DAPP with minimal hassle. It's the easiest way to get started developing on Swarm.
+`bee-js` simplifies development on Swarm by abstracting away many of finer details and quirks of the Bee API so that you can focus on building your dream DAPP with minimal hassle.  
+
+:::info
+On this page you will learn how to install `bee-js` and connect it with your existing app or webpage. 
+:::
+
+
+## Pre-requisites
 
-## Installation 
+- **A live Bee node API endpoint:**
+  You will need the API endpoint from a live Bee node to use `bee-js`. See the Bee docs for [node installation instructions](https://docs.ethswarm.org/docs/bee/installation/quick-start/).
+- **Linux or macOS:** A Unix based operating system is preferred. Windows is supported with some small exceptions. For a smoother experience, Windows users can use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)  
+- **Node.js (v18 or higher)** - [Get Node.js](https://nodejs.org/) 
+- **npm (Node Package Manager)** - [Get npm](https://docs.npmjs.com/)
+- **`swarm-cli`** (optional cli tool for command line node management) - [Get `swarm-cli`](https://github.com/ethersphere/swarm-cli/blob/master/README.md)  
+
+:::tip
+Node.js and npm are not required if you choose to import `bee-js` directly as a script from [unpkg.com](https://unpkg.com/@ethersphere/bee-js/dist/index.browser.min.js). 
+:::
+
+## Installation
 
 <Tabs
   groupId="pcgmng_preferrence"
@@ -46,9 +63,9 @@ yarn add @ethersphere/bee-js --save
   </TabItem>
 </Tabs>
 
-After that you need to import the Bee class and create a bee instance connecting to your Bee node (here we assume it runs on localhost on default port).
+### Node.js (npm or yarn)
 
-Be aware, if you will pass invalid URL the constructor will throw an exception!
+After that you need to import the `Bee` class and initialize an instance of it using our Bee node's API endpoint (here we assume it runs on localhost on the default port).
 
 ```js
 import { Bee } from "@ethersphere/bee-js"
@@ -58,11 +75,7 @@ const bee = new Bee('http://localhost:1633')
 
 That’s it! now you can use the `bee` object.
 
-:::info Run your own Bee node
-You can find out more about running Bee node in the [Bee docs](https://docs.ethswarm.org/docs/installation/quick-start)
-:::
-
-:::tip Using `<script>` import
+### Script Tag
 
 If you include `bee-js` using the `unpkg.com` script link then all the exported components will be available to you
 under global namespace `BeeJs`:
@@ -73,36 +86,48 @@ under global namespace `BeeJs`:
   const bee = new BeeJs.Bee('...')
 </script>
 ```
-:::
 
+## Quickstart with *create-swarm-app*
 
-## Quickstart With *create-swarm-app*
+The `create-swarm-app` tool generates ready‑to‑run skeletons for `bee-js` projects in your chosen setup (CommonJS, ESM, TypeScript, or Vite + TypeScript) with a single command.
 
-The `create-swarm-app` tool makes it easy to get started developing on Swarm. With a single command, it generates the basic scaffolding for a `bee-js` project in your chosen development environment (CommonJS, ESM, TypeScript, or Vite + TypeScript).
-
-:::note WSL WARNING
+:::warning WSL WARNING
 The `create-swarm-app` tool is compatible with Windows, macOS, and Linux. However, using it in combination with [WSL](https://learn.microsoft.com/en-us/windows/wsl/) is discouraged due to potential compatibility issues that may require additional troubleshooting.
 
 That said, the `bee-js` library itself works seamlessly within WSL. If you prefer to develop your project using WSL, you can use `create-swarm-app` to generate the project files on the Windows side, then move them into your WSL environment for development.
 :::
 
-You can use [`create-swarm-app`](https://www.npmjs.com/package/create-swarm-app) to quickly set up scaffolding for a `bee-js` project with the following command:
+### 1) Choose a template and scaffold your app
 
 ```bash
-npm init swarm-app@latest app-name app-type
+npm init swarm-app@latest <app-name> <app-type>
 ```
 
-Replace "app-name" with your app's name, and "app-type" with the type of app you want. Supported types are `node`, `node-esm`, `node-ts` and `vite-tsx`.
+Replace `<app-name>` with your project name, and `<app-type>` with one of:
+
+* `node` – Node.js (CommonJS)
+* `node-esm` – Node.js (ES modules)
+* `node-ts` – Node.js (TypeScript)
+* `vite-tsx` – Vite + React + TypeScript (front‑end)
 
-Start a Swarm project using TypeScript:
+### 2) Back‑end templates (`node`, `node-esm`, `node-ts`)
+
+These outputs give you a minimal script that connects to a Bee node, ensures you have a usable postage batch, then uploads and downloads data via `bee-js`.
+
+Example (TypeScript):
 
 ```bash
 npm init swarm-app@latest my-dapp node-ts
+
+# then
+cd my-dapp
+npm install
+npm start
 ```
 
-Your project structure will look like:
+Project structure:
 
-```bash
+```text
 .
 ├── package.json
 ├── src
@@ -111,13 +136,70 @@ Your project structure will look like:
 └── tsconfig.json
 ```
 
-or using Vite and TypeScript:
+`src/config.ts` — Bee API endpoint (adjust if your node is not on the default):
+
+```ts
+export const BEE_HOST = 'http://localhost:1633'
+```
+
+`src/index.ts` — minimal end‑to‑end flow (init Bee, get/create a stamp, upload, download):
+
+```ts
+import { Bee } from '@ethersphere/bee-js'
+import { BEE_HOST } from './config'
+
+main()
+
+async function main() {
+  const bee = new Bee(BEE_HOST)
+  const batchId = await getOrCreatePostageBatch(bee)
+  console.log('Batch ID', batchId.toString())
+
+  const data = 'Hello, world! The current time is ' + new Date().toLocaleString()
+  const uploadResult = await bee.uploadData(batchId, data)
+  console.log('Swarm hash', uploadResult.reference.toHex())
+
+  const downloadResult = await bee.downloadData(uploadResult.reference)
+  console.log('Downloaded data:', downloadResult.toUtf8())
+}
+
+async function getOrCreatePostageBatch(bee: Bee) {
+  const batches = await bee.getPostageBatches()
+  const usable = batches.find(x => x.usable)
+
+  if (usable) {
+    return usable.batchID
+  } else {
+    // amount and depth are examples; tune for your needs
+    return bee.createPostageBatch('500000000', 20)
+  }
+}
+```
+
+> The CommonJS (`node`) and ESM (`node-esm`) templates include the same basic logic adjusted for their respective module systems.
+
+### 3) Front‑end template (`vite-tsx`)
+
+This option generates a simple React + Vite app that talks directly to Bee from the browser.
+
+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! 
 
 ```bash
 npm init swarm-app@latest my-dapp vite-tsx
 ```
 
-Your project structure will look like:
+```bash
+> npx
+> create-swarm-app my-dapp vite-tsx
+
+Project created
+
+cd my-dapp
+npm install
+npm start
+```
+
+The output files will have this structure:
 
 ```bash
 tree .
@@ -131,6 +213,127 @@ tree .
 └── tsconfig.json
 ```
 
-The exact results will differ slightly depending on which `app-type` you use, but they will all include a `config.ts` or `config.js` file where the Bee node's API endpoint must be specified.
+The logic for purchasing storage and uploading and downloading data is all contained in the `App.tsx` file:
+
+:::tip
+For a step-by-step breakdown of how the code below works, check out the examples section for an explanation of this template along with several others.
+:::
+
+```typescript
+import { BatchId, Bee } from '@ethersphere/bee-js'
+import { useState } from 'react'
+import { BEE_HOST } from './config'
+
+export function App() {
+    const [batchId, setBatchId] = useState<BatchId | null>(null)
+    const [file, setFile] = useState<File | null>(null)
+    const [fileList, setFileList] = useState<FileList | null>(null)
+    const [swarmHash, setSwarmHash] = useState<string | null>(null)
+
+    const bee = new Bee(BEE_HOST)
+
+    async function getOrCreatePostageBatch() {
+        const batches = await bee.getPostageBatches()
+        const usable = batches.find(x => x.usable)
+
+        if (usable) {
+            setBatchId(usable.batchID)
+        } else {
+            setBatchId(await bee.createPostageBatch('500000000', 20))
+        }
+    }
+
+    async function uploadFile() {
+        if (!batchId) {
+            return
+        }
+        const result = await bee.uploadFile(batchId, file)
+        setSwarmHash(result.reference.toHex())
+        setFile(null)
+    }
+
+    async function uploadDirectory() {
+        if (!batchId || !fileList) {
+            return
+        }
+        const result = await bee.uploadFiles(batchId, fileList)
+        setSwarmHash(result.reference.toHex())
+        setFileList(null)
+    }
+
+    const directoryInputAttributes = {
+        webkitdirectory: '',
+        directory: '',
+        multiple: true
+    }
+
+    return (
+        <div>
+            {!batchId && <button onClick={getOrCreatePostageBatch}>Get or create postage batch</button>}
+            {batchId && <p>Batch ID: {batchId.toHex()}</p>}
+            {batchId && !swarmHash && (
+                <div>
+                    <p>Single file upload</p>
+                    <input type="file" onChange={e => setFile(e.target.files![0])} />
+                    <button onClick={uploadFile}>Upload file</button>
+
+                    <p>Directory upload</p>
+                    <input type="file" onChange={e => setFileList(e.target.files)} {...directoryInputAttributes} />
+                    <button onClick={uploadDirectory}>Upload directory</button>
+                </div>
+            )}
+            {swarmHash && <a href={BEE_HOST + '/bzz/' + swarmHash}>Swarm hash: {swarmHash}</a>}
+        </div>
+    )
+}
+```
+
+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. 
+
+![](/img/develop-on-swarm-00.jpg)
+
+After a postage batch is selected, you will be greeted with an interface for uploading data:
+
+![](/img/develop-on-swarm-01.jpg)
+
+After selecting a file to upload, a reference hash to the file will be returned:
+
+![](/img/develop-on-swarm-02.jpg)
+
+#### Using `swarm-cli` to Host on Swarm (optional) 
+
+:::tip
+Learn more about [hosting websites on Swarm](http://docs.ethswarm.org/docs/develop/access-the-swarm/host-your-website) in the official bee-docs.
+:::
+
+Currently 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`. 
+
+```bash
+ npm run build
+```
+
+This will generate a production build in the `/dist` directory, which we can than use `swarm-cli` to upload:
+
+```bash
+swarm-cli upload dist
+```
+
+`swarm-cli` will prompt us to create or select a postage batch, after which it will automatically detect that we are trying upload a website based on the `index.html` file, use that information to set the `--index-document`, complete the upload, and return a hash to us which can now be used by anyone with a Bee node to access our app:
+
+```bash
+? Please select a stamp for this action
+4996787aee78da46b6e32d8141aee89ebb4f2ef3301bf04e0a399247fc414f27 550.296 MB
+Setting --index-document to index.html
+Swarm hash: 764b08bb0f9e82d4bdce951b1ded816bd0417e039828e4308d61ab3035ff60a2
+URL: http://localhost:1633/bzz/764b08bb0f9e82d4bdce951b1ded816bd0417e039828e4308d61ab3035ff60a2/
+Stamp ID: 4996787a
+Usage: 13%
+Capacity (immutable): 550.296 MB remaining out of 628.910 MB
+```
+
+The URL returned in the terminal can now be shared and accessed by anyone with a Bee node:
+
+```bash
+http://localhost:1633/bzz/764b08bb0f9e82d4bdce951b1ded816bd0417e039828e4308d61ab3035ff60a2/
+```
 
-The endpoint is set to the default Bee API endpoint of `http://localhost:1633`, if your node uses a different endpoint you will need to update it in the config file.

src/css/custom.css

@@ -206,7 +206,70 @@ article header h1,
   color: #FFAE42; /* Matches your hover color */
 }
 
-/* Ensure info icon is visible in light mode */
-.alert--info .admonitionIcon_Rf37 svg path {
-  fill: #FFF8DC !important;
+
+[data-theme='dark'] .theme-admonition-note {
+  background-color: #465158;
+  border-color: #C1C9CF;
+}
+
+[data-theme='dark'] .theme-admonition-tip {
+  background-color: #0F6648;
+  border-color: #00DAA1;
+}
+
+[data-theme='dark'] .theme-admonition-info {
+  background-color: #264C6E;
+  border-color: #007FFF;
+}
+
+[data-theme='dark'] .theme-admonition-caution {
+  background-color: #784213;
+  border-color: #F37300;
 }
+
+[data-theme='dark'] .theme-admonition-danger {
+  background-color: #791112;
+  border-color: #F30000;
+}
+
+
+[data-theme='light'] .theme-admonition-note {
+  background-color: #E5E9EC;
+  border-color: #C1C9CF;
+}
+
+[data-theme='light'] .theme-admonition-tip {
+  background-color: #E0FFF4;
+  border-color: #00DAA1;
+}
+
+[data-theme='light'] .theme-admonition-info {
+  background-color: #E2F1FF;
+  border-color: #007FFF;
+}
+
+[data-theme='light'] .theme-admonition-caution {
+  background-color: #FDE9D7;
+  border-color: #F37300;
+}
+
+[data-theme='light'] .theme-admonition-danger {
+  background-color: #FECDCD;
+  border-color: #F30000;
+}
+
+/* Style links inside admonitions */
+.theme-admonition a {
+  font-weight: 600; /* slightly bold, not as heavy as 700 */
+  text-decoration: none; /* remove default underline */
+  border-bottom: 2px solid currentColor; /* underline effect using border */
+  padding-bottom: 1px; /* spacing so border doesn’t touch text */
+}
+
+/* Hover/focus state for better interactivity */
+.theme-admonition a:hover,
+.theme-admonition a:focus {
+  color: var(--ifm-color-primary); /* matches your orange accent */
+  border-bottom-color: var(--ifm-color-primary);
+}
+