Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updates readme #31

Merged
merged 9 commits into from
Jul 15, 2024
Merged

Updates readme #31

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
dc41f9a
working, but no signer
elliotBraem Jul 11, 2024
d17cb6c
complete script
elliotBraem Jul 11, 2024
d8620b0
release cleanup
elliotBraem Jul 11, 2024
c5e8f2e
rename prepare-release
elliotBraem Jul 11, 2024
15d58e3
adds asset-manifest.json
elliotBraem Jul 11, 2024
896e329
update readme
elliotBraem Jul 11, 2024
ab69a3d
reorders sections
elliotBraem Jul 11, 2024
c0551e9
moves test docs to separate readme
elliotBraem Jul 11, 2024
e1e52df
Merge branch 'main' into docs/update
elliotBraem Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 0 additions & 55 deletions .github/workflows/jekyll-gh-pages.yml
View file
Open in desktop

This file was deleted.

19 changes: 13 additions & 6 deletions .github/workflows/npm-publish.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages

name: Node.js Package
name: Publish package

on:
release:
Expand All @@ -20,7 +17,17 @@ jobs:
node-version: 20
registry-url: "https://registry.npmjs.org"
- run: yarn install
- run: yarn prod
- run: npm publish
- name: Prepare the release
run: yarn prepare:release
- name: Commit and push updated package.json (nearfs cid)
run: |
git config --local user.email "[email protected]"
git config --local user.name "GitHub Action"
git add package.json
git commit -m "Update package.json with new nearfs cid [skip ci]"
git push
- name: Publish to NPM
run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

184 changes: 85 additions & 99 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,47 @@
# NEAR BOS Web Component ( custom element )
<!-- markdownlint-disable MD014 -->
<!-- markdownlint-disable MD033 -->
<!-- markdownlint-disable MD041 -->
<!-- markdownlint-disable MD029 -->

This is a Proof of Concept of embedding a NEAR BOS widget into any web application as a Web Component / Custom element.
<div align="center">

Just load react production react bundles into your index.html as shown below, and use the `near-social-viewer` custom element to embed the BOS widget.
<h1>near bos web component</h1>

```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>Near social</title>
<script
defer="defer"
src="/runtime.REPLACE_WITH_BUNDLE_HASH.bundle.js"
></script>
<script
defer="defer"
src="/main.REPLACE_WITH_BUNDLE_HASH.bundle.js"
></script>
</head>
<body>
<h1>NEAR BOS embeddable custom element</h1>
<near-social-viewer></near-social-viewer>
</body>
</html>
```
<p>
<strong>Easily embed a <a href="https://near.social" target="_blank">near social widget</a> into any web app and deploy to <a href="https://web4.near.page/" target="_blank">web4</a>.</strong>
</p>

## Setup & Development
</div>

Initialize repo:
`near-social-viewer` is a [web component (custom element)](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) that implements the [near-social-vm](https://github.com/NearSocial/VM) for rendering code stored on-chain in the [SocialDB](https://github.com/NearSocial/social-db) smart contract (social.near). It is the simplest way to create your own [near social viewer](https://github.com/NearSocial/viewer) and it is the easiest method for embedding [Widgets](https://thewiki.near.page/near.social_widgets) into any web application.

```cmd
yarn
```
## Usage

Start development version:
<details open>
<summary>Via CDN</summary>

```cmd
yarn start
Include the following script tags in your HTML:

```html
<script src="https://cdn.jsdelivr.net/npm/near-bos-webcomponent@latest/dist/runtime.REPLACE_WITH_BUNDLE_HASH.bundle.js"></script>
<script src="https://cdn.jsdelivr.net/npm/near-bos-webcomponent@latest/dist/main.REPLACE_WITH_BUNDLE_HASH.bundle.js"></script>
```

Production build:
Be sure to replace "REPLACE_WITH_BUNDLE_HASH" with the respective hash, which can be found via the asset-manifest:

```cmd
yarn prod
```
<https://cdn.jsdelivr.net/npm/near-bos-webcomponent@latest/dist/asset-manifest.json>

Serve the production build:
</details>

```cmd
yarn serve prod
Once included, you can use the web component in your HTML:

```html
<near-social-viewer src="mob.near/widget/N" initialprops='{"hashtag": "build"}' />
```

## Attributes

The `near-social-viewer` web component supports several attributes:
The web component supports several attributes:

* `src`: the src of the widget to render (e.g. `devs.near/widget/default`)
* `code`: raw, valid, stringified widget code to render (e.g. `"return <p>hello world</p>"`)
Expand All @@ -80,6 +66,64 @@ To support specific features of the VM or an accompanying development server, pr
}
```

## Local Widget Development

There are several strategies for accessing local widget code during development.

### Proxy RPC

The recommended, least invasive strategy is to provide a custom RPC url that proxies requests for widget code. Widget code is stored in the [socialdb](https://github.com/NearSocial/social-db), and so it involves an RPC request to get the stringified code. We can proxy this request to use local data instead.

Either build a custom proxy server, or use [bos-workspace](https://github.com/nearbuilders/bos-workspace) which provides a proxy by default and will automatically inject it to the `rpc` attribute if you provide the path to your web component's dist, or a link to it stored on [NEARFS](https://github.com/vgrichina/nearfs). See more in [Customizing the Gateway](https://github.com/NEARBuilders/bos-workspace?tab=readme-ov-file#customizing-the-gateway).

### Redirect Map

The NEAR Social VM supports a feature called `redirectMap` which allows you to load widgets from other sources than the on-chain social db. An example redirect map can look like this:

```json
{ "devhub.near/widget/devhub.page.feed": { "code": "return 'hello';" } }
```

The result of applying this redirect map is that the widget `devhub.near/widget/devhub.page.feed` will be replaced by a string that says `hello`.

The `near-social-viewer` web component supports loading a redirect map from the session storage, which is useful when using the viewer for local development or test pipelines.

By setting the session storage key `nearSocialVMredirectMap` to the JSON value of the redirect map, the web component will pass this to the VM Widget config.

Another option is to use the same mechanism as [near-discovery](https://github.com/near/near-discovery/), where you can load components from a locally hosted [bos-loader](https://github.com/near/bos-loader) by adding the key `flags` to localStorage with the value `{"bosLoaderUrl": "http://127.0.0.1:3030" }`. There also exists an input at [dev.near.org/flags](https://dev.near.org/flags) to input this url.

### Hot Reload

The above strategies require changes to be reflected either on page reload, or from a fresh rpc request. For faster updates, there is an option in `config` to enable hot reload via dev.hotreload (see [configurations](#configuration-options)). This will try to connect to a web socket server on the same port, or via the provided url, to use redirectMap with most recent data.

This feature works best when accompanied with [bos-workspace](https://github.com/nearbuilders/bos-workspace), which will automatically inject a config to the attribute if you provide the path to your web component's dist, or a link to it stored on [NEARFS](https://github.com/vgrichina/nearfs). See more in [Customizing the Gateway](https://github.com/NEARBuilders/bos-workspace?tab=readme-ov-file#customizing-the-gateway). It can be disabled with the `--no-hot` flag.

## Setup & Local Development

Initialize repo:

```cmd
yarn
```

Start the development version:

```cmd
yarn start
```

Production build:

```cmd
yarn prod
```

Serve the production build:

```cmd
yarn serve:prod
```

## Adding VM Custom Elements

Since [NearSocial/VM v2.1.0](https://github.com/NearSocial/VM/blob/master/CHANGELOG.md#210), a gateway can register custom elements where the key is the name of the element, and the value is a function that returns a React component. For example:
Expand Down Expand Up @@ -117,64 +161,6 @@ bos-workspace dev -g ./path/to/dist

This will start a local dev server using the custom gateway, so you may develop your local widgets through it with access to the custom element.

## Running Playwright tests

To be able to run the [playwright](https://playwright.dev) tests, you first need to install the dependencies. You can see how this is done in [.devcontainer/post-create.sh](./.devcontainer/post-create.sh) which is automatically executed when opening this repository in a github codespace.

When the dependencies are set up, you can run the test suite in your terminal:

```bash
yarn test
```

To run tests visually in the playwright UI, you can use the following command:

```bash
yarn test:ui
```

This will open the playwright UI in a browser, where you can run single tests, and also inspect visually.

If you want to use the playwright UI from a github codespace, you can use this command:

```bash
yarn test:ui:codespaces
```

In general it is a good practice, and very helpful for reviewers and users of this project, that all use cases are covered in Playwright tests. Also, when contributing, try to make your tests as simple and clear as possible, so that they serve as examples on how to use the functionality.

## Local Widget Development

There are several strategies for accessing local widget code during development.

### Proxy RPC

The recommended, least invasive strategy is to provide a custom RPC url that proxies requests for widget code. Widget code is stored in the [socialdb](https://github.com/NearSocial/social-db), and so it involves an RPC request to get the stringified code. We can proxy this request to use our local code instead.

You can build a custom proxy server, or [bos-workspace](https://github.com/nearbuilders/bos-workspace) provides a proxy by default and will automatically inject it to the `rpc` attribute if you provide the path to your web component's dist, or a link to it stored on [NEARFS](https://github.com/vgrichina/nearfs). See more in [Customizing the Gateway](https://github.com/NEARBuilders/bos-workspace?tab=readme-ov-file#customizing-the-gateway).

### Redirect Map

The NEAR social VM supports a feature called `redirectMap` which allows you to load widgets from other sources than the on chain social db. An example redirect map can look like this:

```json
{ "devhub.near/widget/devhub.page.feed": { "code": "return 'hello';" } }
```

The result of applying this redirect map is that the widget `devhub.near/widget/devhub.page.feed` will be replaced by a string that says `hello`.

The `near-social-viewer` web component supports loading a redirect map from the session storage, which is useful when using the viewer for local development or test pipelines.

By setting the session storage key `nearSocialVMredirectMap` to the JSON value of the redirect map, the web component will pass this to the VM Widget config.

You can also use the same mechanism as [near-discovery](https://github.com/near/near-discovery/) where you can load components from a locally hosted [bos-loader](https://github.com/near/bos-loader) by adding the key `flags` to localStorage with the value `{"bosLoaderUrl": "http://127.0.0.1:3030" }`.

### Hot Reload

The above strategies require changes to be reflected either on page reload, or from a fresh rpc request. For faster updates, there is an option in `config` to enable hot reload via dev.hotreload (see [configurations](#configuration-options)), which will try to connect to a web socket server on the same port and use redirectMap with most recent data.

This feature works best when accompanied with [bos-workspace](https://github.com/nearbuilders/bos-workspace), which will automatically inject a config to the attribute if you provide the path to your web component's dist, or a link to it stored on [NEARFS](https://github.com/vgrichina/nearfs). See more in [Customizing the Gateway](https://github.com/NEARBuilders/bos-workspace?tab=readme-ov-file#customizing-the-gateway). It can be disabled with the `--no-hot` flag.

## Configuring Ethers

Since [NearSocial/VM v1.3.0](https://github.com/NearSocial/VM/blob/master/CHANGELOG.md#130), the VM has exposed Ethers and ethers in the global scope, as well as a Web3Connect custom element for bringing up wallet connect.
Expand Down
7 changes: 5 additions & 2 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,11 @@
"test:ui": "npx playwright test --ui",
"test:ui:codespaces": "npx playwright test --ui-host=0.0.0.0",
"nearfs:publish-library:create:car": "ipfs-car pack dist/ --output dist.car",
"nearfs:publish-library:upload:car": "NODE_ENV=mainnet node ./node_modules/nearfs/scripts/upload-car.js dist.car",
"nearfs:publish-library:upload:car": "node ./node_modules/nearfs/scripts/upload-car.js dist.car",
"fmt": "prettier --write '**/*.{js,jsx,ts,tsx,json}'",
"fmt:check": "prettier --check '**/*.{js,jsx,ts,tsx,json}'"
"fmt:check": "prettier --check '**/*.{js,jsx,ts,tsx,json}'",
"prepare:release": "node scripts/prepare-release.mjs",
"clean": "rimraf dist dist.car"
},
"eslintConfig": {
"extends": [
Expand Down Expand Up @@ -97,6 +99,7 @@
"jspm": "^3.1.0",
"mini-css-extract-plugin": "^2.2.2",
"nearfs": "https://github.com/vgrichina/nearfs",
"ora": "^8.0.1",
"os-browserify": "^0.3.0",
"path-browserify": "^1.0.1",
"postcss-loader": "^7.0.1",
Expand Down
Loading
Loading