EVENT: Forge new frontiers: The Weavy + Atlassian Forge hackathonRead more
Quickstart

Add Weavy to Confluence using Atlassian Forge

This quickstart tutorial will show how to use our UIKit Web and add our building blocks as a macro template to your Confluence installation using the Atlassian Forge platform.

Have Forge CLI ready, set the parameters to unlock the tutorial, and get started.

Don't have the parameters? Sign up for free, or sign in and set up your environment to get the parameters.

 Looking for Jira?

1. Create a Forge app

This example creates a Forge app for Confluence; the template used here is a macro.

Open a terminal and create new Forge app 
forge create
  • Enter a name for the Forge app (preferably something with Weavy so it's easy to find later)
  • Select Custom UI as Category
  • Select Confluence as Product
  • Select confluence-macro as the template

2. Install the Weavy UIKit

Open up your project in VS Code or similar. The project consists of a server part (src/index.js) and a client part written in React (static/hello-world).

Open up a terminal and go to the /static/hello-world folder. Install the Weavy UI kit.

Run this in the /static/hello-world folder 
npm install @weavy/uikit-web

3. Modify App.js

Open the App.js file located in the /static/hello-world/src folder. Paste and replace with the following code:
Modify App.js 
import React, { useEffect, useState } from 'react';
import { invoke } from '@forge/bridge';
import { Weavy } from "@weavy/uikit-web";

function App() {  
  const [loaded, setLoaded] = useState(false);

  useEffect(() => {
    const init = async () => {      
      const weavy = new Weavy();
      weavy.url = "WEAVY_URL";
      weavy.tokenFactory = async (refresh) => {
        return "USER_TOKEN";
      };

      setLoaded(true);      
    }

    init();
  }, []);

  if (!loaded) {
    return 'Loading...';
  }
  
  return (
   <div style={{height: '500px', overflow: 'auto'}}>            
      <wy-#### uid="wyuid####"></wy-####>    
    </div>
  );
}

export default App;
  • Line 3 - we import the Weavy UIKit
  • Line 11 - we set the URL to our Weavy backend; in this case WEAVY_URL. You can find this URL in your environment on your Weavy Account.
  • Line 13 - we have a pre-generated access token for a user, strictly for demo purposes.
  • Line 28 - we render the Weavy building block. You can easily change this to any building block. See our docs for more information.

4. Modify manifest.yml

Forge requires some configuration in the manifest.yml for the app to have the correct permissions. Add the following at the end of the current manifest.yml file:
Add this to the end of the manifest.yml file 
permissions:
  external:
    frames: 
      - "*.weavy.io"
    scripts:
      - "*.weavy.io"
    images:
      - "*.weavy.io"
    fetch:
      backend:
        - "*.weavy.io"
        - wss://*.weavy.io
      client:
        - "*.weavy.io"
        - wss://*.weavy.io
  content:
    scripts:
      - 'unsafe-hashes'
      - 'unsafe-eval'
      - 'unsafe-inline'
      - 'blob:'
    styles:
      - 'unsafe-inline'
  scopes:
    - read:confluence-user

5. Build and Deploy

First, we need to build the React project. Go to /static/hello-world folder and run:
Run in the /static/hello-world folder 
npm run build

If you make any changes to the React part, you must build every time before you re-deploy the Forge app.

The next step is to deploy the package to Atlassian. Go to the root folder of the project and run:

Run in the root folder of your project 
forge deploy
When successfully deployed, the last part is to install it - if the macro is already installed add --upgrade to the install command.
forge install
Select Confluence when asked where to install it. Then enter your Atlassian URL - for example your-domain.atlassian.net.

6. Take it for a test run

Navigate to your Confluence  site - your-domain.atlassian.net - and verify that the app works.

The confluence-macro can be tested by creating a new Page and entering /Weavy - or whatever you named the macro to - in the editor.

On this page
Unlock the tutorial with your Weavy API key.
confluence
NEXT

What's next?

This quickstart focused on the front end only, with a pre-generated access token impersonating a demo user.

The next step is to fetch the logged-in user in Confluence, sync it with Weavy, and generate an access token so all of your users can start using our building blocks contextually.
Let's do it

There's more

Check out the other tutorials to understand user sync, access tokens, and how to add Weavy to Jira.

All tutorials