Skip to content

README.md

Latest commit

 

History

History
155 lines (96 loc) · 4.69 KB

README.md

File metadata and controls

155 lines (96 loc) · 4.69 KB
Raw

FWC Plugin with React + TypeScript + Vite

This template should help you get started developing a FWC plugin with React + Typescript + Vite. It provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

<- Home

Generating plugin

FWC provides a cli tool which generates a sample plugin that can be used to help get you started with writing your own plugin:

npm init fwc@latest <name>

Note: You'll need node installed to run the above command: https://nodejs.org/en/download/

To get started, open a terminal and enter in the following command:

npm init fwc@latest my-first-plugin

After being prompted with a few questions to help setup your plugin, the plugin project will be created and installed. The cli tool provides templates to create components using lit, react or svelte:

image

Installing

To install run the following command:

npm install

Running

To run the dashboard in dev mode cd into the directory that was created in the last step and run the following command:

npm run dev

You should see the following in the terminal:

image

The dashboard should launch automatically in the browser. If not, open it manually using link shown in the terminal. (http://localhost:5173 for me)

You should see the dashboard in the browser:

image

From here you should be able to navigate to your component which you can add and test in the browser:

image

Building and importing into dashboard app

Before the plugin can be imported into the dashboard app the plugin must first be built. Run the following command to build

npm run build

A plugin folder should be generated:

image

Warning

This folder should not modified manually since your changes will be overwritten whenever the build command is run.

Within the build file you'll find a few important files and folders:

  • index.js which is the root javascript file which the dashboard app will import.
  • assets folder which contains images and other static files that your plugin uses. These are copied over from the public/assets folder.
  • plugin.json which contains metadata like the plugin name, description and version used by the dashboard app for display purposes.

To import the plugin open the app and click the File > Plugins menu item:

image

This should open the plugins dialog:

image

Click Load Plugin which open up an open folder dialog. Navigate to your plugin and select the plugin folder generated with the npm run build command:

image

You should now see the plugin loaded in the dialog:

image

The app must be refreshed to view the changes:

image

Theming

Theming in the FWC dashboard app is done using CSS variables.

As an example take the following style rule for the my-react-element component:

color: white;

To make this rule themable change it to the following:

color: var(--my-react-element-color, white);

--my-react-element-color is the CSS variable. CSS variables are prefixed with --. To ensure uniqueness and to prevent accidentally overwriting existing rules prepend your variable with the element name. white is the default value if a theme is not set.

To add per theme rules add the following code:

import { addThemeRules } from '@frc-web-components/app';

addThemeRules('dark', {
  '--my-react-element-background': 'cadetblue',
  '--my-react-element-color': 'black',
});

addThemeRules('light', {
  '--my-react-element-background': 'cornflowerblue',
  '--my-react-element-color': 'white',
});

Including Static Assets

Static assets like such as images should be placed in the /public/assets folder. They can be included into the app by calling the getAssetUrl function. For example:

import { getAssetUrl } from '@frc-web-components/app';

const url: string = getAssetUrl('party.svg');

The above URL can then be used as the src of an image element:

<img src="{url}" />