We have a clone function for initializing a bos-workspace from existing widgets an account may hold. This is helpful when creating a bos-workspace for an existing account, so we don't need to copy and paste widget code around.

I tried using this on a mistyped account Id and got an error:

This is because the account I tried (near-catalog.near) does not exist. I would expect a clearer error, something like:

"Are you sure this account exists? : near-catalog.near "

The dev command allows a custom gateway path via the -g flag, which is useful when building with gateways with custom components.

Example usage:

trylivepeer.near/package.json

  "scripts": {
    "bw": "bos-workspace",
    "dev": "pnpm run dev:gateway && pnpm run dev:apps",
    "dev:gateway": "cd gateway && pnpm run build",
    "dev:apps": "pnpm run bw ws dev -g gateway/dist/"
  },

Following the README for Publishing libraries to NEARFS, adapt this flag to allow either the path to a dist or nearfs url

https://ipfs.web4.near.page/ipfs/bafybeicu5ozyhhsd4bpz4keiur6cwexnrzwxla5kaxwhrcu52fkno5q5fa/

Rather than all at one time.

Sort of like git add and git commit

Overview

This Epic tracks all the tasks and issues required to launch the first stable release of bos-workspace. Our goal is to ensure that the release is dev-friendly, well-tested, and well-documented.

Core functionalities

• #31
• #22
• #24
• #19
• #30
• #21
• #28
• #26
• #47

Complete documentation

• #46

Testing & Bugs

The code is missing tests, we need to improve the test coverage to ensure nothing breaks with new versions based on the core functionalities.

• #18

This would use bos-cli-rs, but how should we manage these in our repository?

It may be nice for them to be separate from the widgets we are actively working on -- like a node_modules (bos_modules)

You can currently use bos-cli-rs to download all widgets from a specific near account.

This solution may be related to #26

Possibly could be one of the first dev tools; the ability to toggle "container" vs full-width.

Devs developing specific components may want "container"; devs building fully branded websites may want full-width.

Bigger teams like to include preview deploys in their pull requests; this typically involves the developer deploying to a dedicated account and sharing a link -- although this can be difficult when working on multiple stories at one time (either needs a dedicated account per story, or need to rotate through the deploys depending on the order they are reviewed).

A possible solution (only in testnet) is to create github workflow that generates an implicit account via near-cli-rs, then deploys to this account and shares the preview link automatically.

A couple of ecosystem projects set up their Github workflows to deploy to testnet, then to mainnet.
For example, see near-discovery-components (although this uses bos-loader exclusively).

To do this, there are different replacements file for each environment that get passed to bos-loader replacements flag.

See:

We should be able to support the same in bos-workspace.

Acceptance Criteria

• Builders should be able to assign different account Ids according to environment, e.g "mob.near" in mainnet and "eugenethedream" in testnet
• Builders should be able to assign different contract ids according to environment, e.g "devgovgigs.near" in mainnet and "thomas.preview.testnet" in testnet
• Builders should be able to assign other aliases according to environment(?)

Initialize a documentation site for bos-workspace and how to use it.

This documentation site can double as the local development setup

So they can be used by VM.require

While trying to deploy the full Potlock repository to a new account, it gets a 520 error on deploy via bos-cli-rs

We can either call the cli in chunks or make a change to cli

See the deploy command in bos-workspace here

This needs to be completed: lib/deploy.ts

This should be able to work within a workspace or for a singular app (bos.workspace.json or just a bos.config.json).

You can reference the git workflow for deploying code in what the steps should be, see this: https://github.com/NEARBuilders/bos-workspace/blob/main/.github/workflows/deploy.yml

bw-legacy === false means use the current (v1.0.0-alpha.*) bos-workspace. We have this flag here because some projects are still using an old version of bos-workspace.

In a local bos-workspace with multiple apps, it looks like :

While the apps are named:

The app name should take priority.

This broke in latest alpha version:

neither installing it globally or in the repository exposed bos-workspace or bw to be used.

We should make sure this works before transferring it over.

Most projects using bos-workspace are set to this version atm:

   "bos-workspace": "github:nearbuilders/bos-workspace#main"

We want to make it easier for others to develop new features for bos-workspace.

Let's add a contributing guide and steps for how to implement new features locally, as well as how to add tests to validate the features.

Can draw inspiration from Vlad Frolov's TS Starter

https://github.com/frol/bos-component-ts-starter/blob/main/src/components/subfolder/my-nested-component.tsx

Use surcrase to transpile during build

Readme is not the best place to put docs, let's make them on-chain. This is a good opportunity to use NEARBUILDERS/create

When developing locally, there can be some unexpected behavior and discrepancy between what is local and what has been published to social contract.

For example, in below, you'll see two errors pop up in potlock.near/widget/Components.Nav:

First, it throws a "props.hrefWithParams" function not found error, although the local version of Components.Nav and all of its children do not use this function (the published version does).

Also, you'll see "potlock.near/widget/Cart.NavItem is not found", which is a new widget that has been added locally and is not yet published. Since we are pulling from local, this shouldn't be an issue, but the error showing is why I suspect a request for published version is made first.

Turning off wifi and running the app shows no errors.

Additional notes

• "VM is dead" is also a common error you'll find, although it seems to go away as the application becomes more performant.
• Need to confirm if this is only an issue with hot reload and local gateway, check if it works with flags + no hot reload
• Why is the VM making a request when the key exists in redirect map?

This used to be a feature of bos-workspace 0.0.1, but was only partially carried over from the refactor.

We're able to use local widgets, but what if I want to reference local data when I do bos-workspace dev?

For example, I have a Social.get(${config_account}/project/nested.projectId) in my code to reference the JSON I have stored at project/nested/projectId in my workspace?

The prior implementation of this can be found HERE, feel free to use it as a reference. In short, it loops through all the files in designated directories and builds a large data.json.

I think in the new implementation, we should do the same, but associate it with a configuration in the bos.config.json that designates which directories should be uploaded. For example:

bos.config.json

{
    "account": "sample.near",
    "data": { 
      "include": ["type", "thing", "project"]
    }
  }

Where the strings in "include" are references to the directory names in same level as the bos.config.json. An example of a repository that would use this feature is hyperfiles.

This data should be exposed through the dev server so it is used during RPC proxy, see in lib/server. It could use the same devJson, just save outside of "components".

Acceptance criteria

• Local data can be referenced in workspace code
• Throws error if an "included" directory does not exist
• Should watch for changes in included directories
• Test coverage

I did a clone to download all of devs.near's widgets.

(from /examples, see contributing guide)
../bin/bw.js clone devs.near

I checked them out locally

../bin/bw.js ws dev

They appeared. I went through and deleted a ton because I don't need all these widgets.

I run them again...
../bin/bw.js ws dev

but these files are still showing in bos-workspace portal, despite not in my filesystem.

After deleting files, they should no longer show in my workspace.

We have the -g flag for a custom gateway used for development-- now we want to be able to set a gateway and read the "index" from bos.config.json, so we can deploy this resulting /dist

Deploying to web4

Text guide

This is an example of a current Github workflow utilizing bos-workspace:

BluntDAO

name: Deploy Components to Mainnet
on:
  push:
    branches: [main]
jobs:
  deploy-widgets:
    runs-on: ubuntu-latest
    name: Deploy widgets to social.near (mainnet)
    env:
      BOS_DEPLOY_ACCOUNT_ID: ${{ vars.BOS_DEPLOY_ACCOUNT_ID }}
      BOS_SIGNER_ACCOUNT_ID: ${{ vars.BOS_SIGNER_ACCOUNT_ID }}
      BOS_SIGNER_PUBLIC_KEY: ${{ vars.BOS_SIGNER_PUBLIC_KEY }}
      BOS_SIGNER_PRIVATE_KEY: ${{ secrets.BOS_SIGNER_PRIVATE_KEY }}
      NETWORK_ID: mainnet

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Install near-social CLI
        run: |
          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/FroVolod/bos-cli-rs/releases/download/v0.3.1/bos-cli-v0.3.1-installer.sh | sh
      
      - name: Install bos-workspace from dev branch
        run: |
          npm install -D bos-workspace
  
      - name: Build the workspaces
        run: |
          npm run build

      - name: Deploy widgets
        working-directory: ./build/bluntdao
        run: |
          bos components deploy "$BOS_DEPLOY_ACCOUNT_ID" sign-as "$BOS_SIGNER_ACCOUNT_ID" network-config mainnet sign-with-plaintext-private-key --signer-public-key "$BOS_SIGNER_PUBLIC_KEY" --signer-private-key "$BOS_SIGNER_PRIVATE_KEY" send

Notice that we need to set the working directory to ./build/bluntdao

We could replace this with a template, like this one where deploy account, signer account, public key, private key, and the app name (bluntdao) get passed as variables to it

See #390

After the latest update (v1.0.0-alpha.11), deeply nested routes such as:

./widget/deeply/nested/index.tsx
./widget/very/deeply/nested/index.tsx

Have stopped working.

We would expect these to build correctly, to:

./widget/deeply.nested.index.tsx
./widget/very.deeply.nested.index.tsx

If a widget looks like this on the social contract:

{
  [accountId]: {
    widget: {
     [widgetName]: {
        "": JSON.stringify(code),
        "metadata": {
          name: "",
          description: "",
        }
      } 
  }
  }
}

We could extend metadata to include an array of users to attribute. This could be handled from bos-workspace, with an ultimately goal of it potentially populated based on mappings of a user's github handle with their near account.

Windows users are getting mismatched paths when building, see below:

Then on click, it goes here: Source code for "hyperfiles.near/widget/hyperfile/index" is not found
This does not occur on windows.

We should expect the paths in the image to be:
hyperfiles.near/widget/adapter.github, etc

And the link should be the same. The dot should be replacing this character.

Easier way of styling components with Tailwind can be achieved by incorporating either PostCSS, TailwindCLI or TailwindCDN directly in the gateway and when components are ready to be published user can/should compile the CSS file (can also be automated)

I believe for testing purposes users shall be able to have easy way to inject anything they want into the development gateway provided anyway

The resulted CSS file can be uploaded and referenced later in an wrapper component similar to this implementation by Andria

I am currently on my Windows machine. the exact error that occurred during the installation was

error: failed to run custom build command for openssl-sys v0.9.97

Caused by:
process didn't exit successfully: C:\Users\SASWAT~1\AppData\Local\Temp\cargo-installW4uxhg\release\build\openssl-sys-a52d4764de55824a\build-script-main (exit code: 101)
--- stdout
cargo:rerun-if-env-changed=X86_64_PC_WINDOWS_MSVC_OPENSSL_NO_VENDOR
X86_64_PC_WINDOWS_MSVC_OPENSSL_NO_VENDOR unset
cargo:rerun-if-env-changed=OPENSSL_NO_VENDOR
OPENSSL_NO_VENDOR unset
running "perl" "./Configure" "--prefix=C:\Users\SASWAT~1\AppData\Local\Temp\cargo-installW4uxhg\release\build\openssl-sys-8d11540cf2537ff2\out\openssl-build\install" "--openssldir=SYS$MANAGER:[OPENSSL]" "no-dso" "no-shared" "no-ssl3" "no-tests" "no-comp" "no-zlib" "no-zlib-dynamic" "--libdir=lib" "no-md2" "no-rc5" "no-weak-ssl-ciphers" "no-camellia" "no-idea" "no-seed" "no-capieng" "no-asm" "VC-WIN64A"

--- stderr
thread 'main' panicked at C:\Users\saswat marpureddy.cargo\registry\src\index.crates.io-6f17d22bba15001f\openssl-src-300.1.6+3.1.4\src\lib.rs:585:9:

Error configuring OpenSSL build:
Command: "perl" "./Configure" "--prefix=C:\Users\SASWAT~1\AppData\Local\Temp\cargo-installW4uxhg\release\build\openssl-sys-8d11540cf2537ff2\out\openssl-build\install" "--openssldir=SYS$MANAGER:[OPENSSL]" "no-dso" "no-shared" "no-ssl3" "no-tests" "no-comp" "no-zlib" "no-zlib-dynamic" "--libdir=lib" "no-md2" "no-rc5" "no-weak-ssl-ciphers" "no-camellia" "no-idea" "no-seed" "no-capieng" "no-asm" "VC-WIN64A"
Failed to execute: program not found

note: run with RUST_BACKTRACE=1 environment variable to display a backtrace
warning: build failed, waiting for other jobs to finish...
error: failed to compile bos-cli v0.3.6 (https://github.com/FroVolod/bos-cli-rs#46037ed0), intermediate artifacts can be found at C:\Users\SASWAT~1\AppData\Local\Temp\cargo-installW4uxhg

Update to lava rpc, use this as reference

As part of Move "default widget src" replacement to bos-workspace.

Allows user to provide index in bos.config.json which will act as index widget with -g flag

Enable this in the VM so we can see data-component key, will be helpful for tests.

See in VM changelog: https://github.com/NearSocial/VM/blob/master/CHANGELOG.md#250

I attempted to implement w/ deploy, but it didn't seem to work?

After setting up multiple bos-workspaces across the ecosystem, I've encountered some recurring feedback.

Typically, bos-workspaces have not been used as monorepos handling multiple different apps and will instead use one app + deploy accountId, which will be setup in a Github Action

A common flow I've had to do is the following:

For bluntdao, I needed to initialize a bos-workspace, pull in existing widgets, then set up the workflow

mkdir bluntdao-components
cd bluntdao-components

mkdir apps
mkdir apps/bluntdao
mkdir apps/bluntdao/widget
touch apps/bluntdao/bos.config.json
touch apps/bluntdao/widget/hello.jsx

cd apps/bluntdao
bos components download bluntdao.near
// this downloads all bluntdao components to a /src directory
 // now we need to move them all to the widget directory 
mv src/widget/* widget/.  

npm init (create package.json)
npm install bos-workspace

// create npm run dev and npm run build in package.json -> bw dev, bw build

// copy over github workflows
// modify github workflow working directory to be the app name (bluntdao)

npm run dev

And then sometimes, if there are multiple apps, such as genadrop; instead of dedicate different accounts for each app, they add a prefix like in genadrop, so there are prefixes GenaDrop and CPlanet, and so you can have a structure that looks like this:

apps/bluntdao/widget/bluntdao/hello.jsx

I think the multi-app flow is powerful, and maybe GenaDrop and CPlanet should be following it rather than what they are doing now deploying to the same account

But it is very common to set up a github repository for only one app + to only configure one deploy and signer account for it for the Github Action; and so the deep directories repeating the same app name can be confusing.

I feel like both should be supported, especially considering the context of #25 and #19; but it may mean changing default behavior or reducing a layer; food for thought

Creating this story to keep track of all the projects + repositories that are using bos-workspace and must be updated/maintained.

Ideally we can update these to a stable version with a uniform structure, as well as using the reusable workflow, so there is minimal maintenance going forward.

• Discover BOS (has own gateway, too): https://github.com/nearbuilders/discoverbos
• Build DAO (own gateway): https://github.com/NEARBuilders/gateway
• Potlock: https://github.com/PotLock/bos-app
• Proof of Vibes: https://github.com/proofofvibes/vibes-components
• Blunt DAO: https://github.com/BluntDAO/bluntdao-bos-components
• Embeds: https://github.com/NEARBuilders/embeds
• Maps: https://github.com/NEARBuilders/maps
• Create: https://github.com/NEARBuilders/create
• Liberty DAO: https://github.com/NEARBuilders/libertydao
• Hackoween: https://github.com/nearbuilders/hackoween
• Questverse: https://github.com/Quest-Protocol/questverse-monorepo

Currently, running bos-workspace dev in a new repository starts a server on a new port (e.g., 8080) if 4040 is already in use. This feature would allow developers to work on multiple projects simultaneously without needing to switch ports.

This way, I can check out multiple repositories, run "bos-workspace dev", and the files in the repo will be appended to the existing server.

For example, I am working on Build DAO gateway repository, which uses the Feed widget in bos-blocks. Currently, I drag and drop the "apps" I need, but this risks duplication or changes detaching from original repo

This used to be a feature of bos-workspace 0.0.1, but was only partially carried over from the refactor. To be completed after #99.

The purpose of the command is to upload other data, besides widget to the social contract. As you can see, looking at an account's data tree on social contract, see every.near's here, there can be other data aside from widget such as "type", "thing", "project"... we want to enable the ability to manage and upload these files from bos-workspace.

The prior implementation of this can be found HERE, feel free to use it as a reference. In short, it loops through all the files in designated directories and builds a large data.json, converts to base64, then uploads to social contract via near cli command.

I think in the new implementation, we should do the same, but associate it with a configuration in the bos.config.json that designates which directories should be uploaded. For example:

bos.config.json

{
    "account": "sample.near",
    "data": { 
      "include": ["type", "thing", "project"]
    }
  }

Where the strings in "include" are references to the directory names in same level as the bos.config.json. An example of a repository that would use this feature is hyperfiles.

Acceptance criteria

• Upload command uploads data to social.near contract
• Command throws error if an "included" directory does not exist
• Test coverage
  • should throw error if included directory does not exist
  • should call social contract with correct values & base64 encoded json

When trying to use the bos-workspace init command via npx bos-workspace init, I get the following error:

➜ npx bos-workspace init
✔ What NEAR AccountId deploys your project? … test.near
No such file or directory: /Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/bos-workspace/templates/js
No such file or directory: test.near/_gitignore
No such file or directory: test.near/_github
Error: No files match the pattern: test.near/README.md
    at /Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/lib/helpers/glob-async.js:23:23
    at f (/Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/once/once.js:25:25)
    at Glob.<anonymous> (/Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/node_modules/glob/glob.js:148:7)
    at Glob.emit (node:events:514:28)
    at Glob._finish (/Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/node_modules/glob/glob.js:194:8)
    at done (/Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/node_modules/glob/glob.js:179:14)
    at Glob._processSimple2 (/Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/node_modules/glob/glob.js:688:12)
    at /Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/node_modules/glob/glob.js:676:10
    at Glob._stat2 (/Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/node_modules/glob/glob.js:772:12)
    at lstatcb_ (/Users/ebraem/.npm/_npx/ab7f07b18dde6119/node_modules/replace-in-file/node_modules/glob/glob.js:764:12)
Something went wrong when generating your app. You may need to delete the folder at test.near

This error does not happen if I access bos-workspace directly, outside of npx.

Just as I am able to toggle environment on an application like nearblocks:

I want to be able to do this on the bos-workspace gateway. I should be able to sign in with a testnet account. This environment environment should be passed to the NearSocial/VM so contract calls in widgets reflect correct environment.

The github action is just a deploy, we can find other ways to run it.

Rather than just "appAccount", what if the bos.config.json allowed the deploy and signer account for deploying these widgets in via smart contract?

Project Board: https://github.com/orgs/NEARBuilders/projects/5

The /*__@replace:alias__*/ is hard to type and not optimal. Maybe we should switch it to something more concise, easier to write and read with less constraints without conflicting with other code.

We need a syntax that is language agnostic, we want the commands to be parsed in every type of comments one line or multi line, be it in JS, HTML, CSS, JSONC or any language. Using the @ in js will also help with syntax highlighting.

for example to import a module:

// @alias(hello)
// @import(module)
// @account
/* @alias(hello) */

<!-- @alias(hello) -->

/* @alias(hello) */

// @skip
{}

This will break projects using the older syntax, if we choose to implement it we have to support both syntaxes until we remove the old in a future major release.

@elliotBraem, you used bos-workspace more than anyone, so what do you think about this? is a an unnecessary change or an improvement?

Currently, the default gateway will show this screen on start:

I want to be able to override this with a custom widget. This can come from a "workspace" field in bos.config.json or bos.workspace.json

It should be able to be overridden depending on environment.

I do not have Windows, but I have faced this issue with a few devs.

In an app director, a L1 widget such as widget/home.jsx works fine, but a L2 widget like widget/home/index.jsx will not work when accessing via widget/home.index.

We need some to add some options to the cli, mainly:

• bw dev --gateway-port 5555 --loader-port 5556 define ports to use with the servers.
• bw dev --no-gateway launch bos-loader without the gateway.
• bw dev --no-hot disable web-socket server and only use http server.

create-bos-app is a hackathon project created by @sethfork. I've been using it a lot for starting new projects and when directing others to get started.

Seth has agreed that we can combine the two of these and integrate it with bos-workspace.

In implementing this, we can draw inspiration from wenderson's create-alem-dapp which utilizes existing template git repositories (e.g. we could use app-template ) to initialize projects.

I think this could enable us to not need to set /flags on a gateway (although this would still be an available option)

Either a gateway or near-bos-webcomponent

Now that #77 command has been implemented, we should use it in the reusable git workflow

https://github.com/NEARBuilders/bos-workspace/blob/main/.github/workflows/deploy.yml

Important

Maintain the bw-legacy === true path! There are still projects that depend on it's functionality. The change must not impact this workflow.

Right now, you must go through the flow and select an app:

But this isn't helpful in CI/CD. We should be able to specify the app name:

bos-workspace deploy Hello