Edit files with Workspaces
Published on
Goal: This tutorial provides hands-on practice in setting up and using Workspaces so that you can use Workspaces in your own projects. Workspaces enable you to save changes that you make within DevTools to source code that's stored on your computer.
Prerequisites: Before beginning this tutorial, you should know how to:
Overview #
Workspaces enable you to save a change that you make in Devtools to a local copy of the same file on your computer. For example, suppose:
- You have the source code for your site on your desktop.
- You're running a local web server from the source code directory, so that the site is accessible at
localhost:8080
. - You've got
localhost:8080
open in Google Chrome, and you're using DevTools to change the site's CSS.
With Workspaces enabled, the CSS changes that you make within DevTools are saved to the source code on your desktop.
Limitations #
If you're using a modern framework, it probably transforms your source code from a format that's easy for you to maintain into a format that's optimized to run as quickly as possible. Workspaces is usually able to map the optimized code back to your original source code with the help of source maps. But there's a lot of variation between frameworks over how they use source maps. Devtools simply can't support all the variations.
Workspaces is known to not work with these frameworks:
- Create React App
If you run into issues while using Workspaces with your framework of choice, or you get it working after some custom configuration, please start a thread in the mailing list or ask a question on Stack Overflow to share your knowledge with the rest of the DevTools community.
Related feature: Local Overrides #
Local Overrides is another DevTools feature that is similar to Workspaces. Use Local Overrides when you want to experiment with changes to a page, and you need to see those changes across page loads, but you don't care about mapping your changes to the page's source code.
Step 1: Setup #
Complete this tutorial to get hands-on experience with Workspaces.
Set up the demo #
Open the demo. In the top-left of the editor, there's a randomly-generated project name.
Figure 1. A Glitch project with a randomly-generated name
Click the randomly-generated project name. For example, in Figure 1 you would click desert-cycle.
Select Advanced Options > Download Project.
Figure 2. The Download Project button, highlighted in blue
Close the tab.
Unzip the source code and move the unzipped
app
directory to your desktop. For the rest of this tutorial this directory will be referred to as~/Desktop/app
.Start a local web server in
~/Desktop/app
. Below is some sample code for starting upSimpleHTTPServer
, but you can use whatever server you prefer.cd ~/Desktop/app
Open a tab in Google Chrome and go to locally-hosted version of the site. You should be able to access it via a URL like
localhost:8080
. The exact port number may be different.Figure 3. The demo
Set up DevTools #
Press Command+Option+J (Mac) or Control+Shift+J (Windows, Linux, Chrome OS) to open the Console panel of DevTools.
Figure 4. The Console panel
Click the Sources tab.
Click the Filesystem tab.
Figure 5. The Filesystem tab
Click Add Folder To Workspace.
Select
~/Desktop/app
.Click Allow to give DevTools permission to read and write to the directory. In the Filesystem tab, there is now a green dot next to
index.html
,script.js
, andstyles.css
. These green dots mean that DevTools has established a mapping between the network resources of the page, and the files in~/Desktop/app
.Figure 6. The Filesystem tab now shows a mapping between the local files and the network ones
Step 2: Save a CSS change to disk #
Open
~/Desktop/app/styles.css
in a text editor. Notice how thecolor
property ofh1
elements is set tofuchsia
.Figure 7. Viewing
styles.css
in a text editorClose the text editor.
Back in DevTools, click the Elements tab.
Change the value of the
color
property of the<h1>
element to your favorite color. Remember that you need to click the<h1>
element in the DOM Tree in order to see the CSS rules applied to it in the Styles pane. The green dot next tostyles.css:1
means that any change you make will get mapped to~/Desktop/app/styles.css
.Figure 8. Setting the
color
property of theh1
element togreen
Open
~/Desktop/app/styles.css
in a text editor again. Thecolor
property is now set to your favorite color.Reload the page. The color of the
<h1>
element is still set to your favorite color. This works because when you made the change, DevTools saved the change to disk. And then, when you reloaded the page, your local server served the modified copy of the file from disk.
Step 3: Save an HTML change to disk #
Try changing HTML from the Elements panel #
Warning: The workflow that you're about to try doesn't work. You're trying it now so that you don't waste time later trying to figure out why it's not working.
Click the Elements tab.
Double click the text content of the
h1
element, which saysWorkspaces Demo
, and replace it withI ❤️ Cake
.Figure 9. Attempting to change HTML from the DOM Tree of the Elements panel
Open
~/Desktop/app/index.html
in a text editor. The change that you just made isn't there.Reload the page. The page reverts to its original title.
Optional: Why it doesn't work #
Note: This section describes why the workflow from Try changing HTML from the Elements panel doesn't work. You can skip this section if you don't care why.
- The tree of nodes that you see on the Elements panel represents the page's DOM.
- To display a page, a browser fetches HTML over the network, parses the HTML, and then converts it into a tree of DOM nodes.
- If the page has any JavaScript, that JavaScript may add, delete, or change DOM nodes. CSS can change the DOM, too, via the
content
property. - The browser eventually uses the DOM to determine what content it should present to browser users.
- Therefore, the final state of the page that users see may be very different from the HTML that the browser fetched.
- This makes it difficult for DevTools to resolve where a change made in the Elements panel should be saved, because the DOM is affected by HTML, JavaScript, and CSS.
In short, the DOM Tree !==
HTML.
Change HTML from the Sources panel #
If you want to save a change to the page's HTML, do it via the Sources panel.
Click the Sources tab.
Click the Page tab.
Click (index). The HTML for the page opens.
Replace
<h1>Workspaces Demo</h1>
with<h1>I ❤️ Cake</h1>
. See Figure 11.Press Command+S (Mac) or Control+S (Windows, Linux, Chrome OS) to save the change.
Reload the page. The
<h1>
element is still displaying the new text.Figure 11. Line 12 has been set to
I ❤️ Cake
Open
~/Desktop/app/index.html
. The<h1>
element contains the new text.
Step 4: Save a JavaScript change to disk #
The Sources panel is also the place to make changes to JavaScript. But sometimes you need to access other panels, such as the Elements panel or the Console panel, while making changes to your site. There's a way to have the Sources panel open alongside other panels.
Click the Elements tab.
Press Command+Shift+P (Mac) or Control+Shift+P (Windows, Linux, Chrome OS). The Command Menu opens.
Type
QS
, then select Show Quick Source. At the bottom of your DevTools window there is now a Quick Source tab. The tab is displaying the contents ofindex.html
, which is the last file you edited in the Sources panel. The Quick Source tab gives you the editor from the Sources panel, so that you can edit files while having other panels open.Figure 12. Opening the Quick Source tab via the Command Menu
Press Command+P (Mac) or Control+P (Windows, Linux, Chrome OS) to open the Open File dialog. See Figure 13.
Type
script
, then select app/script.js.Figure 13. Opening
script.js
via the Open File dialogNotice the
Save Changes To Disk With Workspaces
link in the demo. It's styled regularly.Add the following code to the bottom of script.js via the Quick Source tab.
console.log('greetings from script.js'); document.querySelector('a').style = 'font-style:italic';
Press Command+S (Mac) or Control+S (Windows, Linux, Chrome OS) to save the change.
Reload the page. The link on the page is now italic.
Figure 14. The link on the page is now italic
Next steps #
Congratulations, you have completed the tutorial. Click the button below to receive your prize.
Last updated: • Improve article