Pageblox-react NPM

Pageblox

Pageblox is an open-source React tool that generates preview links with a real-time, collaboration review interface. It replaces the back-and-forth screen recordings and conversations that usually occur when giving feedback on UX/UI changes.

Contributions are welcome! You can try out the alpha today.

Installation

React Library

You'll first need to obtain a project key, which can be obtained by signing up here.

Run the following command in the root of your React application using your terminal:

npm install pageblox-react

Github Actions

To create preview links, a Github Actions workflow is required. This will build the React project on every push to a branch and deploy it using Github Pages. The URL will be in the form of https://<USERNAME>.github.io/<REPO>/.

Creating the workflow file

Start by creating a .github/workflows folder, and add a deploy.yml file. Depending on the React library used, the build folder path will change. The following example is for a Vite project, so the folder path is dist.

To toggle Pageblox, you want to create an environment variable in your repo, and set it equal to true upon build.

Lastly, ensure that your repository is configured to have its GitHub Pages site deployed from a branch, by setting the source for the deployment under Settings > Pages of your repository to Deploy from branch. Best practice is to name this branchgh-pages. You can learn more about deploying from a branch here.

name: Build and Deploy
on: [push]
permissions:
  contents: write
jobs:
  build-and-deploy:
    concurrency: ci-${{ github.ref }}
    runs-on: ubuntu-latest
    env:
      VITE_DISPLAY_PREVIEW: "true"
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v3
      - name: Install and Build 🔧 
        run: |
          npm ci
          npm run build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: dist # The folder the action should deploy. Adjust this value based on your react library.

Usage

After installation, you need to wrap your application with PagebloxProvider and import the pageblox.css file.

Finally, create an environment variable named DISPLAY_PAGEBLOX with the appropriate prefix depending on your platform, and initialize it to false.

Using NextJS

Use _app.js to utilize the pageblox wrapper. You can find more info here.

import { PagebloxProvider } from 'pageblox-react'
import 'pageblox-react/dist/pageblox.css'

export default function App({ Component, pageProps }) {
  return (
    <PagebloxProvider projectId="playgroundKey"
    enabled={import.meta.env.NEXT_PUBLIC_DISPLAY_PAGEBLOX === 'true'}>
      <Component {...pageProps} />
    </PagebloxProvider>
  )
}

Using Create React App / Vite Example

import React from 'react'
import ReactDOM from 'react-dom/client'
import { BrowserRouter } from 'react-router-dom'
import { PagebloxProvider } from 'pageblox-react'
import App from './App.jsx'
import './index.css'
import "pageblox-react/dist/pageblox.css"

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <PagebloxProvider projectKey="sample-key"
    enabled={import.meta.env.VITE_DISPLAY_PAGEBLOX === 'true'}>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </PagebloxProvider>
  </React.StrictMode>,
)

Generating a preview link

Once you've imported the PagebloxProvider & CSS file, as well as created an appropriate environment variable used in the actions workflow, go ahead and push changes to a remote branch.

You can view the progress of this workflow under the Actions tab in your repository.

Once it's completed, visit https://<USERNAME>.github.io/<REPO>/ and you'll see the Pageblox widget on the bottom right of your app. Click on it to start commenting!