Step 1: Getting Started with Widget Development

Welcome to widget development! In this step, you’ll set up your development environment and get familiar with the widget development workflow.

🎯 What You’ll Accomplish

By the end of this step, you’ll have:

• Development environment ready - All prerequisites installed and configured
• Widget starter kit cloned - Your own copy of the widget template
• Development server running - Local widget development environment active
• Project structure understanding - Know how widget projects are organized

🏢 Check With Your Organization First

Before diving into the standard tools, check with your platform team to see if your organization provides:

• Custom widget starter kit - Organization-specific template with company standards
• Internal development guidelines - Company-specific setup instructions
• Custom development tools - Organization-specific CLI tools or workflows
• Internal widget registry - Private package registry for dependencies

If your organization has custom tools, use those instead! The concepts in this tutorial will still apply.

🔧 Prerequisites Check

Ensure you have the following installed:

Node.js and Package Manager

# Check Node.js version (22+ required)
node --version

# Check yarn version(4.x.x)
yarn --version

📦 Cloning the Widget Starter Kit

Let’s get the standard 1fe widget starter kit:

1. Clone the Repository

# Clone the widget starter kit
git clone https://github.com/docusign/1fe-widget-starter-kit.git my-first-widget

# Navigate to the project
cd my-first-widget

2. Install Dependencies

# Install all dependencies
yarn install

This will install all the necessary dependencies for widget development

3. Explore the Project Structure

Let’s understand what you just cloned:

my-first-widget/
├── src/                    # Your widget source code
│   ├── components/         # Reusable React components
│   ├── contract.ts         # Widget contract definition
│   ├── app1.tsx           # Main widget entry point
│   └── widget.ts          # Default widget export
├── tests/                  # Test files
├── .1fe.config.ts         # Widget build and runtime configuration
├── package.json           # Dependencies and scripts
└── README.md              # Project documentation

🏗️ Understanding Key Files

Widget Entry Point (src/app1.tsx)

This is your main widget component:

src/app1.tsx

import { platformProps } from "@1fe/shell";
import React, { useEffect } from "react";
import { Router as Widget } from "./components/router";
import { withProvider } from "./withProvider";
import { WidgetProps } from "./contract";

const RootWrapper: React.FC<WidgetProps> = (props) => {
  useEffect(() => {
    platformProps.utils.appLoadTime.end();
    console.log("props", props);
  }, []);

  return <Widget {...props} />;
};

export default withProvider(RootWrapper);

Widget Contract (src/contract.ts)

Defines the interface between your widget and the platform:

src/contract.ts

import { PlatformPropsType } from "@1fe/shell";

export type HostPropsContract = Record<string, unknown>;

export type WidgetProps = {
  host: HostPropsContract;
  platform: PlatformPropsType;
};

Configuration (.1fe.config.ts)

Controls how your widget is built and deployed:

.1fe.config.ts

import { OneFeConfiguration } from "@1fe/cli";
import { getBaseConfig } from "@1fe/sample-widget-base-config"; // this is the redistributed package for the organization

const configuration: OneFeConfiguration = {
  baseConfig: getBaseConfig,
};

export default configuration;

🚀 Starting the Development Server

1fe Instance Required

Important: This command requires a running 1fe instance to work properly. If your organization doesn’t have a 1fe instance set up yet, you’ll need to follow Tutorial 1: Setup and Deploy a 1fe POC to get your 1fe instance up and running locally first.

Now let’s get your widget running locally:

# Start the development server
yarn dev

You should see output similar to:

✔ Webpack
  Compiled successfully in 3.82s

<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://127.0.0.1:8080/
<i> [webpack-dev-server] 404s will fallback to '/index.html'
post action hook executed
[dev] Opening the widget in the playground with the URL:
        http://localhost:3001/playground?widgetUrl=http%3A%2F%2F127.0.0.1%3A8080%2Fjs%2F1fe-bundle.js

What just happened?

• The 1fe CLI compiled your widget
• Started a local development server
• Made your widget available at a local URL
• Enabled hot reloading for development

🔍 Verifying Your Setup

Let’s make sure everything is working:

1. Check the Bundle URL

Open your browser and visit:

http://localhost:8080/js/1fe-bundle.js

You should see JavaScript code (the compiled widget bundle).

2. Open in playground

If your team doesn’t have their own 1fe instance, you can open the widget in our demo 1fe instances playground by visiting:

http://demo.1fe.com/playground?widgetUrl=http%3A%2F%2F127.0.0.1%3A8080%2Fjs%2F1fe-bundle.js

3. Make a Test Change

Edit src/app1.tsx and change the heading:

src/app1.tsx

import { platformProps } from "@1fe/shell";
import React, { useEffect } from "react";
import { Alert } from "antd";
import { Router as Widget } from "./components/router";
import { withProvider } from "./withProvider";
import { WidgetProps } from "./contract";

const RootWrapper: React.FC<WidgetProps> = (props) => {
  useEffect(() => {
    platformProps.utils.appLoadTime.end();
    console.log("Widget loaded with props:", props);
  }, [props]);

  return (
    <div>
      <Alert
        message="🎉 Widget Ready!"
        type="success"
        style={{ margin: "8px" }}
        closable
      />
      <Widget {...props} />
    </div>
  );
};

export default withProvider(RootWrapper);

Save the file and watch your terminal - you should see the widget recompile automatically and your browser should show a pretty banner at the top of the page with a close button.

📁 Understanding Widget Architecture

Platform Integration

Your widget runs within the 1fe platform and has access to:

• Platform utilities - Shared functions for logging, navigation, etc.
• Shared dependencies - React, design systems, and common libraries
• Shell context - Platform-wide state and configuration
• Event system - Communication with other widgets and the shell

Development Workflow

The typical development cycle is:

1. Code - Write widget functionality in src/
2. Test - Use the playground for immediate feedback
3. Build - Compile with yarn build:widget
4. Deploy - Push to your organization’s deployment pipeline

🎉 Success!

Congratulations! You now have a fully functional widget development environment. Your widget is compiled, served locally, and ready for development.

👉 Next Step

Now that your development environment is ready, let’s learn how to use the 1fe Playground to develop and test your widget interactively.

→ Step 2: Using the Playground for Development

In the next step, we will explore the playground to learn more of it’s features.

---