🧑💻Contributing for Developers
Last updated
Last updated
If you want to contribute and don't know where to start, here is a step-by-step for a complete lifecycle, from idea to deployment.
If you have an idea that is not already in discussion or issues, please start a discussion or reach out on discord
If you are a DEVLOPER, and you want to contribute to the Builder UI, your first step is to become familiar with our design system in figma. Start with the first page of our Design Docs. And for our design system & components see the Webstudio Library. Please read the docs carefully and throughly so you can use our design system properly to create a UI that looks like it's a natural part of Webstudio. If any part of the design is confusing or intimidating you can reach out to us on Discord with questions or feedback.
After submitting an enhancement or a bug we need to agree on a solution. You can jump into implementation right away, but be aware that we have to agree on the solution in the end. Communicating the problem you are solving and why you think the approach you are taking is the best is key for a quick process.
In fact, we are happy to help communicating your ideas, so if you are not sure - talk to us on discord.
When the implementation is in a mergeable state, a core team member will deploy it to production.
Open the Webstudio repository on GitHub:
Click the green "Code" button.
Select "Open with Codespaces".
If you don't have a Codespace already, click "New codespace".
The Webstudio project will now open in a Codespace with the development environment pre-configured.
Wait for the setup to complete:
The installation process will take some time as the environment is set up and dependencies are installed.
This setup is defined by the postCreateCommand in the .devcontainer configuration.
Run the development server:
After the setup completes, open the terminal in Codespaces.
Run the following command:
If you don't see Network: https://wstd.dev:5173/ when it's done, try executing the command once more.
Change the port protocol to HTTPS (Ports > Right Click > Change Port Protocol)
Open the application in your browser
Go to Ports and open the Forwarded Address
VS Code installed: Download VS Code
Docker installed: Install Docker
Install the "Dev Containers" extension in VS Code:
Open VS Code.
Go to the Extensions view by clicking the Extensions icon in the Activity Bar on the side of the window.
Search for "Dev Containers" and click Install. Alternatively, you can install it from the recommended extensions listed in the Webstudio project.
Fork and clone the Webstudio repository:
Fork the repository on GitHub.
Clone your forked repository to your local machine.
Open the repository in VS Code:
Open VS Code.
Select "File" > "Open Folder" and choose your project folder.
Reopen in Container:
Once your folder is open, you might see a notification asking if you want to reopen in a container. Click "Reopen in Container".
If you don't see a notification, press F1, type Dev Containers: Reopen in Container, and select it.
VS Code will now build the Docker container and open the Webstudio project inside it. This process will take some time as the environment is set up and dependencies are installed.
Run the development server:
After the setup completes, open the terminal in VS Code.
Run the following command:
Open the application in your browser:
After running pnpm dev, you will see a URL in the console that looks like this:
Cmd + click on the URL in the console to open it in your browser.
Docker installed: Install Docker
Fork and clone the Webstudio repository:
Fork the repository on GitHub.
Clone your forked repository to your local machine.
Navigate to the project directory:
Set up the PostgreSQL database:
Navigate to the .devcontainer folder and execute the SQL setup with Docker Compose:
Go to the project root directory and run the following command to create the database schema:
Start the development server:
When downloading the app you will have two options for login and they both work in different ways.
Dev login will create you a dev account so you don't need to be online or create a github app. To enable you create a file .env.development in apps/builder and include two lines:
To login in the app click on the "Dev Login" button and paste the first four characters of your AUTH_SECRET in the input.
To log in as another user in dev mode, use the first four characters of your AUTH_SECRET, followed by : and any email address. For example: `abcd:example@email.com`\
To login and use GitHub login you will need to create an OAuth app with the following values:
When creating the app with
http://localhost:3000you will need to always open your app athttp://localhost:3000for the GitHub login to work.
After the app is created you will need to create a client secret and then copy that value and your client id to the .env file:
You are done! 🎉
For this we current use relative-deps and the way you can run both things is the following:
Git clone the sdk at https://github.com/webstudio-is/webstudio-sdk
In the builder run pnpm dev and in another window run pnpm watch:sdk
This will trigger a build of the SDK whenever make changes to it and that will in turn reload your builder.
import your Git repository into Vercel, and it will be deployed.
Add DATABASE_URL to env variables
Redeploy
If you'd like to avoid using a Git repository, you can also deploy the directory by running Vercel CLI:
It is generally recommended to use a Git repository, because future commits will then automatically be deployed by Vercel, through its Git Integration.
Follow this guide if you would like to release a new version one of our package available to npm.
The flow looks like the following:
Modify the code in a branch other than main.
Every commit on any branch builds and publish to npm with --dry-run options.
If everything looks fine, bump the version in package.json, open a PR and if it's approved, merge it.
Every commit on main will try publish to npm in case of any files or release process (GitHub Action) changed inside the package directory.
If VS Code shows you an "Open Browser" button, it will lead you to the wrong URL as they are only watching ports. Be sure to use wstd.dev and NOT localhost. The proper URL will show in the console.
