Local development

Given that the Outreach context is exclusive to the Outreach environment, it's imperative to establish a secure connection over the local network for development purposes.

Prerequisites

1. Node.js : Install Node.js which includes npm (Node Package Manager), required to manage the dependencies and run the React application.
2. OpenSSL : Ensure OpenSSL is installed on your system to generate self-signed SSL certificates. This is often pre-installed on UNIX-based systems (Linux, macOS), but for Windows, you may need to install it manually or use a tool like Git Bash that includes it.
3. Webpack : The application must be bundled with Webpack, so ensure that Webpack is installed and properly configured for your project.

Installation

npm config set @getoutreach:registry https://npm.pkg.github.com
npm install @getoutreach/extensibility-sdk

Setting up the application

Start by setting up a simple React application. This involves initializing the Outreach context, which is only available within the Outreach extension environment. The initialization occurs within a React component, as demonstrated below:

import React, { useEffect } from "react";
import extensibilitySdk from '@getoutreach/extensibility-sdk';

const Extension: React.FC = () => {
  // Using the useEffect hook to initiate the Outreach context
  useEffect(() => {
    const init = async () => {
      const outreachContext = await extensibilitySdk.init();
      // Handle the outreachContext as needed
    };
    init();
  }, []);

  return (
    // Your component JSX
  );
};

Generate SSL Certificate for HTTPS

You need to generate a self-signed SSL certificate or get one from a Certificate Authority (CA). For local development, a self-signed certificate will suffice.

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout localhost.key -out localhost.crt -subj "/CN=extension.outreach-dev.com"

This will create a localhost.key file for your private key and a localhost.cert file for your self-signed certificate, valid for 10 years (3650 days). Remember, browsers will not trust self-signed certificates by default, and you will need to proceed through security warnings or add an exception for your certificate.

You can replace extension.outreach-dev with the domain you want to use locally.

Update the hosts file

The hosts file maps hostnames to IP addresses. On your local machine, add your domain to this file.

• On Windows , edit C:\Windows\System32\drivers\etc\hosts .
• On macOS and Linux , edit /etc/hosts .

Add the following code:

127.0.0.1    extension.outreach-dev.com

Now extension.outreach-dev.com will resolve to your local machine.

Update Webpack configuration

Modify your webpack.config.js or the relevant configuration file to enable HTTPS and specify your certificate and key.

const fs = require('fs');

//...

devServer: {
  https: {
    key: fs.readFileSync('./localhost.key'),
    cert: fs.readFileSync('./localhost.crt'),
  },
  host: 'extension.outreach-dev.com',
  //...
},

Remember to replace ./localhost.key and ./localhost.crt with the actual paths to your key and certificate files.

Run your Webpack Development Server

Start your Webpack server. Make sure your local development server is running with HTTPS enabled, as configured with your Webpack development server.

yarn start # Or the appropriate command to start your Webpack server

Creating a test app

Upon successful setup of the Webpack Development Server, the next step involves registering the application with the Outreach platform.

1. Navigate to the Outreach extension dashboard.
2. Proceed to create a new extension. During this process, specify the extension.outreach-dev.com as the "Hosting URL". This will route requests from the Outreach extension to your local server.

For more information check out Your first extension