Deploy your first change to a scratch org
In this tutorial we will claim a scratch org, deploy the project into it, change a piece of metadata, and watch that change appear in a running Salesforce org. By the end you will have driven the whole inner development loop once, from your editor to a live org.
Follow every step in order. Some steps do more than they seem to — that is fine; we are building the feeling of the loop, and understanding follows later.
Before we begin
We assume you have finished Set up the toolchain locally, and that sf org list
shows a Dev Hub marked as your default. If it does not, ask your project lead for Dev Hub access
before continuing.
Step 1 — Create a scratch org
Run:
create:scratch first looks for a ready org in the pool; with no pool available it simply creates a
fresh one, so this works from a clean start. It takes a while: watch it create the org, apply the
metadata workarounds, push force-app, run the setup script, and import data. When it finishes you
will see the new org's username near the end of the output (something like test-abc123@example.com)
and, because it is not running on CI, it opens the org in your browser automatically. We now have
a disposable Salesforce org with the project's metadata and data in it, set as our default org.
Step 2 — Confirm you are in the org
Look at the browser tab that opened. You are already logged in to the scratch org — notice that you did not type a password; the toolchain authenticated the org for you. If the tab has closed, reopen it any time with:
Step 3 — Find a field to change
In your editor, open force-app/ and find any *.field-meta.xml file. Inside it you will see a
<description> element, for example:
We are going to change this description. It is the safest possible first change: a field description affects no logic and cannot break anything.
Step 4 — Make the change
Edit the text inside <description>…</description> and save the file:
Step 5 — Deploy it
Send the change to your scratch org through the toolchain, not a bare sf call:
deploy wraps sf project deploy start with the project's metadata workarounds. By default it also
runs the project's local Apex tests as part of the gate, so expect this to take a bit longer than a
bare deploy would. You will see a short progress report ending in Deploy Succeeded. Notice that only
your one changed component is listed as deployed — Salesforce compares source to org and sends only
what differs.
Step 6 — See it in the org
Switch back to the browser tab from Step 2 and navigate to the field (Setup → Object Manager → the object → Fields & Relationships → your field). The description now shows your edited text. Let's confirm the loop closed: the words you typed in your editor are now live in a Salesforce org.
Step 7 — Clean up
Scratch orgs are disposable and count against a Dev Hub limit, so we delete this one now that we are done:
What we did
We claimed an org, deployed the project into it, changed a field, deployed that change, and saw it in the org — the complete inner loop, once, end to end. You have now done by hand the essential thing the pipeline automates for real changes.
When you are ready to move from doing to understanding — why create:scratch does so much, what
happens on a real deploy — read
Delta deployments and quick deploys and
Scratch org pooling. To do specific jobs, the
how-to guides are next.