Skip to main content

Project Setup

Qodly's API simplifies the creation of Custom Components using React through its dedicated CLI tool, @qodly/cli. This API streamlines the initiation of the React project, allowing developers to build and share reusable custom components within the Qodly community, providing a user-friendly integration into Webforms through a straightforward drag-and-drop mechanism.

Initial Setup


Before setting up your React project, make sure your development environment meets the following prerequisites:

  • Node.js version 20 or above.
  • npm version 10 or above.

Project Initialization

Open your terminal and execute the following command to initiate a new project:

npx @qodly/cli init

This command utilizes the Qodly CLI tool to set up the initial project structure.


Follow the prompts to name your project, e.g., "qodly-example".

Installing Dependencies

Navigate to the generated project folder (e.g., "qodly-example") using the terminal:

cd /folderPath/qodly-example

Then install the necessary npm dependencies:

npm i

Configuring Environment

To ensure the smooth operation of the Standalone Webform Editor, you can choose between running a Cloud instance or a 4D instance. Each setup has specific requirements for setting up and running your development environment.

Run a Cloud Instance

To utilize a Cloud instance of the Qodly platform, it's essential to configure environment variables that allow your custom components to communicate securely:

  • API_KEY: Bound to the Administration port, crucial for accessing administrative features securely.

  • PROXY_SERVER: Specifies the API endpoint, critical for connecting your application to the backend services.

These variables should be set within environment configuration files located at the root of your project, adjacent to package.json. Here's how to do it:

  1. Create Environment Files: Depending on your deployment stage, you might have .env.development for development settings and .env.production for production settings.

  2. Add Variables to the Files:

    API_SECURE= true

Ensure to keep your API_KEY secure and never expose it in client-side code where unauthorized users could access it.

Ensure the API_KEY is of type "Administration" to access administrative features securely. This key should never be exposed in client-side code to prevent unauthorized access.

Run a 4D Instance

To operate a 4D instance effectively, you need to run a 4D Web Server alongside your React project. Failing to do so can lead to connection issues that prevent the Webform Editor from functioning correctly.


If the 4D Web Server is not running, you might encounter the following error in your terminal:

[vite] http proxy error: /rest/$catalog/$all
Error: connect ECONNREFUSED
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1595:16)

This error indicates that your local server setup is trying to connect to a 4D instance at but cannot establish a connection, resulting in the Standalone Webform Editor not loading.

Dependencies Overview

Production Dependencies

Below is an overview of the production dependencies listed in the package.json file:

@ws-ui/webform-editorProvides the Webform Editor functionality for Qodly, allowing developers to create and edit webforms.
reactA JavaScript library for building user interfaces, used in the project for creating custom components.
react-domReactDOM provides DOM-specific methods for React, enabling interaction with the DOM and rendering components.

Development Dependencies

Below is an overview of the development dependencies listed in the package.json file:

@qodly/cliCommand-line interface tool for initializing and managing Qodly projects.
@types/reactTypeScript type definitions for React, providing type information for React when using TypeScript.
@types/react-domTypeScript type definitions for ReactDOM, providing type information for ReactDOM when using TypeScript.
@typescript-eslint/eslint-pluginESLint plugin for TypeScript, identifying and reporting patterns found in TypeScript code.
@typescript-eslint/parserTypeScript parser for ESLint, allowing ESLint to lint TypeScript code.
@vitejs/plugin-react-swcVite plugin for React with SWC, facilitating fast web development with React. SWC is a JavaScript/TypeScript compiler.
@ws-ui/webform-editor-standaloneStandalone version of the Qodly webform editor, used for local development and testing.
eslintESLint is a linter tool for identifying and reporting patterns found in ECMAScript/JavaScript code.
eslint-config-prettierESLint configuration that turns off rules unnecessary or conflicting with Prettier.
eslint-plugin-prettierESLint plugin for Prettier, allowing ESLint to run Prettier as an ESLint rule.
eslint-plugin-react-hooksESLint plugin for React hooks, providing ESLint rules specific to React hooks.
eslint-plugin-react-refreshESLint plugin for React refresh, offering ESLint rules related to the React refresh feature.
typescriptTypeScript is a superset of JavaScript that adds static typing to the language.
viteVite is a fast web development build tool supporting modern JavaScript and React. Used for local development and builds.

Development Workflow

Running the Development Server

Launch Qodly Studio in local mode with only the Standalone Webform Editor using the following command:

npm run dev

Used when actively developing your project. It provides a local environment where you can make changes and test components.

When you run npm run dev, it runs the server locally at:

Local: http://localhost:5001/

The project utilizes Vite for rapid development and efficient serving of the project in dev mode.

Building the Project

Build your project for production using the following command:

npm run build

Used to generate a production-ready build of your entire project, the build process creates a compressed folder named with a uniquely generated ID.


The ID generated is established during the initialization of a new project and remains consistent throughout the project's lifecycle. As a result, each execution of the build ensures that the folder contains the same generated ID.

Locate this compressed folder in your project directory, ready for drag-and-drop onto the upload feature in Qodly Studio for installation.

Generating a New Component

Add a new component to your project with the following command:

npm run generate:component

Follow the prompts to name the new component.


A project can contain multiple custom components, as in a custom Chart project with various components contributing to the final custom Chart.

The generate:component command internally executes qodly new component, which then generates the necessary files and folders for the component within the components directory.


Custom components must use unique names to avoid conflicts with Qodly Studio's built-in components. If a custom component shares the same name as a built-in component, the custom component will take precedence when dragged and dropped onto the webform editor.

The components directory serves as the repository for custom components:

- components
- ExampleComponent
- ExampleComponent.render.tsx
- ExampleComponent.settings.tsx
- ExampleComponent.config.tsx
- index.tsx

While developers have the flexibility to implement their initial component in their preferred manner, adhering to the suggested structure is recommended

Refer to the custom component structure section for detailed information.