Scaffold extensions for the Blip platform
To start your extension using this template, run the command below:
npm create blip-extension@latestThen follow the prompts!
See create-blip-extension for more details on supported templates.
If for some reason the command above doesn't work, simply cloning this repository should suffice.
- React
- TypeScript or JavaScript
- Tailwind CSS
- Blip Design System
- Iframe Message Proxy
- ESLint, Prettier & CSpell
- Husky with lint-staged and commitlint
- i18next
- Cypress
Note: Although recommended, you don't have use this template to create Blip extensions. You can use any stack as long as you can render your web app as an iframe in the Blip portal.
In this section, you will learn how to set up and develop a Blip extension.
This guide assumes that you have basic knowledge of JavaScript and React concepts, and know how to use the Blip platform.
In technical terms, A blip extension is simply a web application viewed as an iframe inside the Blip platform. It can do everything a web app can, and also communicate with the main platform though the iframe-message-proxy API.
Begin by scaffolding your project following the instructions on the installation section.
After running the development server, you will be able to see the extension running on http://localhost:3000/.
To be able to communicate with the main platform, your extension must be running inside the Blip platform. Due to company policy, I can't show you how to do it here, so if you are interested in learning how to do this, please reach out.
The Blip platform provide multiple API endpoints that allow you to communicate with the main platform.
See the utility functions inside src/lib/iframe-messages to get an idea of how that looks like.
You can look how to do a specific thing on the Blip Documentation.
As I understand, not everything is fully documented. If you can't find what you want to do in the documentation, I would recommend asking around in the Blip forum.
As a web application, you can use any API you want, or develop your own.
Simply make HTTP requests inside your extension. See how to do this in React.
This template comes with a CI/CD pipeline already set up for Azure DevOps. You can see it in azure-pipelines.yml. However, this pipeline is specific to my organization (Blip), and uses internal templates.
If you are not part of Blip, you can use this pipeline as a reference to create your own.
These files are related to the pipeline, and can be removed if you are not using it:
- azure-pipelines.yml
- Dockerfile
- charts/*
The old template used Jest and RTL (React Testing Library), however, there were some issues with it, that would make tests very painful to write:
- JSDOM doesn't support web components (widely used by Blip Design System)
- RTL doesn't actually render the component, it only renders a representation of it. This causes a lot ot problems and the need to constantly mock things.
To fix this issue, I decided to switch over to Cypress. Cypress is way more powerful, and alongside of solving the problems mentioned above, it also:
- Allows for better coverage (It actually renders the component)
- Visual testing (so you can see if your component is rendering correctly)
- Easier and more intuitive API
Now it's up to you. Build what you want to, and don't forget to submit it to the Blip Store once it's done. Happy coding!
To have an up-to-date project, verify when this template was last updated. If you believe it was too long ago, consider recreating it following (and changing if necessary) the steps below.
-
Create a new React project using Vite. When prompted, choose React with TypeScript + SWC or JavaScript + SWC. Instructions here.
-
Install Blip Design System. Instructions here.
2.1. Add
optimizeDeps: { exclude: ['blip-ds/loader'] }to./vite.config.ts. This is a workaround to make blip-ds work with Vite. See issue -
Install Tailwind. Instructions here.
-
Install the Nunito Sans font using Fontsource. Instructions here.
4.1. Choose which font weights & styles to use, to cut down on payload sizes. See configuration.
4.2. Set it as the default font with Tailwind CSS. Instructions here.
-
Install Prettier. Instructions here.
5.1. Configure Prettier. See configuration.
-
Install ESLint. Instructions here.
6.1. Integrate Prettier with ESlint. Instructions here.
6.2. Integrate Tailwind CSS with ESLint. Instructions here.
6.3. Configure ESLint. See configuration.
-
Configure Git hooks
7.1. Install husky. Instructions here.
7.2. Install lint-staged. Instructions here.
7.3. Install commitlint. Instructions here.
-
Configure VScode settings
8.1. Configure settings. See configuration.
8.2. Configure extensions. See configuration.
-
Install CSpell. Instructions here.
9.1. Add CSpell's Brazilian Portuguese Dictionary. Instructions here.
9.2. Add CSpell's Spanish Dictionary. Instructions here.
9.3. Configure CSpell. See configuration.
-
Install i18next. Instructions here.
10.1. Add type safety. Instructions here.
-
Install React Router Dom Instructions here.
-
Install Testing Libraries. Instructions here.
12.1. Install Vitest. Instructions here.
12.2. Install Cypress. Instructions here.
-
Install the iframe-message-proxy package
13.1. If using TypeScript, add package's types See definitions.
13.2. Create iframe-message-proxy helper functions (src/lib/iframe-messages)
-
Finishing touches
14.1. Set the website title to "Blip Extension".
14.2. Set the website favicon. See favicon.
14.3. Install
tailwind-blip-ds. Instructions here.14.5. Add blip language detector. See code.
Note: To keep the project's root folder clean, transform the configuration files with few lines into keys on package.json. Example: The file .lint-staged.config.cjs can be a lint-staged key on package.json.