🧑💻Contributing for Developers
Process
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 Taylor Nowotny with questions or feedback. I'm happy to give a tour of the design system to anyone who asks.
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.
Builder installation
Install Node.js
Install PNpm
npm i -g pnpm
Install Postgres, in here there are three main options:
Install the official Postgres app - Make sure to remember the username and password you choose since you will need it for the connection string
On a mac you can also install Postgres.app and in that case you will have no password and your username will be the same as your system username.
Intall Docker Engine, run
docker compose -f ./apps/builder/docker-compose.yaml up -d
to start Postgres (use PGPORT environment variable in case of default is already used).
Clone the repository
git clone git@github.com:webstudio-is/webstudio-builder.git
Connect to the database: add a database URL to the env variables by creating an .env file in the
apps/builder
and adding thereDATABASE_URL=postgresql://user:pass@localhost/webstudio
orDATABASE_URL=postgresql://user@localhost/webstudio
if using Postgres.app.Run
pnpm install
- install dependenciesRun
pnpm build
Run
pnpm migrations migrate
- apply database migrationsRun
pnpm dev
- URL will be logged
Login locally
When downloading the app you will have two options for login and they both work in different ways.
Dev login
Dev login will create you a dev account so you don't need to be online or create a github app. To enable you must have two lines in your .env
:
To login in the app click on the "Dev Login" button and paste the first four character of your AUTH_SECRET
in the input.
GitHub Login
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:3000
you will need to always open your app athttp://localhost:3000
for 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! 🎉
Develop builder and SDK in parallel
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 runpnpm watch:sdk
This will trigger a build of the SDK whenever make changes to it and that will in turn reload your builder.
Builder deployment to Vercel
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.
Release new version of a package
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.
Last updated