googlechrome / web.dev

The frontend, backend, and content source code for web.dev

web.dev [Archived]

Note: This site is migrated to a new platform and this repository is available in a read-only mode. We will not be merging new pull requests. Please raise content issues in the new issue tracker.

web.dev is the ultimate resource for developers of all backgrounds to learn, create, and solve on the web. It's meant to not only educate developers, but help them apply what they've learned to any site they work on, be it personal or business.

---

[Archived README]

Building the site 🏗

You'll need a recent version of Node: v14 (LTS) or higher. To check your node version run node -v in your terminal.

If you don't have node, or if you need to upgrade, we recommend using the Node Version Manager (nvm).

Clone the repo

git clone https://github.com/GoogleChrome/web.dev.git

Change directory into the folder created

cd web.dev

Install dependencies

npm ci

Start a local server to preview the site

npm run dev

Open http://localhost:8080/ to see the site locally. Changes to assets will rebuild the site. Refresh to see your changes.

Set up build flags

Building the entire site can take a while because it's around one thousand pages. If you want to massively speed up your build times, we suggest setting some build flags to ignore certain sections.

• Create a .env file at the root of your project
• Add the following:

# Ignore ALL site content
ELEVENTY_IGNORE=true

# Only build the directories you're working on.
# Note, this is a JSON string so you must use double quotes.
ELEVENTY_INCLUDE=["blog", "vitals"]

Environments 🌳

Set ELEVENTY_ENV=prod to force production builds. This is the default when running "stage" or "deploy". No other options for ELEVENTY_ENV are supported, although our Eleventy site config will default to 'dev' if unspecified.

The production build currently requires a lot of memory, to the point where node might exit with errors along the line of

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

v8::internal::V8::FatalProcessOutOfMemory(v8::internal::Isolate*, char const*, bool) [node]

The exact amount of heap space required varies from computer to computer and version of node. If you need a local production build, but run out of memory, you can increase the heap size by adding --node-options '--max_old_space_size=8192' (to assign 8gb of heap space) to the npm command, prior to run. For instance:

ELEVENTY_ENV=prod npm --node-options '--max_old_space_size=8192' run build

Staging 🕺

When you send in a pull request it will be automatically staged for you. Keep an eye out for the netlify bot to comment on the pull request with your unique URL.

Deploying the site 🚀

Automatic deploys

The site will build and deploy the main branch automatically every hour, Mon-Fri. If you've just merged an article then it should go live at the top of the next hour.

Manual deploys

To manually deploy the site you'll need to be a member of one of these Google teams:

• web.dev-eng
• web.dev-owners

1. Navigate to the Cloud Build Triggers page.
2. Click the RUN button for the trigger named Deploy.
3. In the side drawer that opens up, click the RUN TRIGGER button for the trigger for the main branch.

NOTE: web.dev auto deploys every hour if there is a new commit in the main branch. Manual deploys should only occur when a build fails or if auto deploys are disabled.

Debugging 🐛

If you need to debug the site's build process:

1. Add a debugger statement to .eleventy.js
2. Run npm run debug:eleventy
3. Go to about://inspect to attach to the running process.

web.dev's Issues

Licensing!

• All codelab content needs to use the shortened Google license.
• All code in this repo related to infra needs to have license headers.

Profile: address filter reseting on focusout / clicking impact chip.

1. Click a score category
2. The audit list filters
3. Click an impact chip

Filtering is reset.

This happens because the card loses focus. If you click on any other space in the page, other than a card, the filtering logic will be removed as well. Do we want to remove the focusout behavior instead?

Add lighthouse IDs to generated _auditpaths.md

• The generated _auditpaths.md file contains links to all the guides on web.dev. (These are not necessarily categorized properly yet).
• We have to filter these to the guides relevant to the failing audits (or the previously failed, now fixed audits) on the client side, as DevSite isn't server-side rendered. (We hide irrelevant guides.)

We can't currently do this because the audit IDs aren't included in the generated HTML. So we need a way for web_todo_list (part of Google's internal codebase) to filter based on the currently failing audits.

1. Modify the content generation such that each "guide" is annotated with its corresponding lighthouse IDs (perhaps data-lighthouse="auditid auditid auditid...).
   a. modify build scripts here, stage new content (using yarn build --stage)
   b. (I don't think we correctly categorize each guide—the Lighthouse category it fails. This is just a heading to add.).
2. Modify web-todo-list to, when it is provided with failing audit IDs, filter the visible guides (regardless of their completion status).

"show live" launches a new tab.... maybe a tooltip or hint?

My first experience tapping on show live was so fast to render in a new tab it was almost disorientating.

could be nice to have a tooltip or some hint that this will send you out of the experience?

Console button not easily accessible

With the update to the Glitch embeds, there's no console button present anywhere

The only way it seems accessible is to let the user know to open the glitch separately and then remix the application. For any codelabs that cover any bash commands, this is a bit of an issue

Add Travis

It'll help catch npm run build errors and we may be able to use it to sync to Glitch.

Measure page: headings and URL

https://web.devsite.corp.google.com/profile

1. 'Measure' is at the top of the page in close proximity three times, which looks odd.

2. Measure H1 appears to be too close to the blue bar above it.

3. Measure page title doesn't match the URL (why 'profile'?)

Content feedback for discover-performance-opportunities-with-lighthouse

Content: https://web.dev/fast/discover-performance-opportunities-with-lighthouse

• “Press Control+Shift+J or Command+Shift+J (Mac) to open DevTools.” Add “(Windows)” - it only says (Mac) at present.
• CMD-Shift-J on my Mac external keyboard opened the “Downloads” area, not DevTools.
• “Run Lighthouse from Chrome DevTools” - the numbered points after images are being reset to 1 for each image.
• “Click the Audits tab. If you don't see this tab, click More Panels *and then select Audits from the list.” “and then select” formatting is messed up, I assume because spaces are in the right place for "" formatting.
• “Make sure that the *Clear Storage checkbox is enabled.” - “” markup messed up again.
• “For example, if you run some audits with *Simulated Fast 3G, 4x CPU Slowdown throttling enabled ”. "" formatting messed up.
• “Hover over a metric to learn more about it. Click *Learn more to read documentation about it.” - "" formatting messed up.

Text issues with "Serve modern code..." doc

This doc: Serve modern code to modern browsers for faster page loads
It cuts off at the end (seems to be missing a heading and more content?). Also, the code boxes don't look properly formatted.

Need syntax highlighting for code

@samthor any idea why the highlighter isn't running against our markdown? Is that a client-side operation that DevSite's JS runs, or do they do that at build time with their markdown parser?

Topic 'expand' down-arrows UI is unclear (and the up-arrows don't work)

The topic down ('expand') arrows are a long way from the text they're associated with, and I don't think it's clear what they're for. A standard summary/details element might be better, like the example below.

Also, once you've clicked the down arrow, clicking the up arrow doesn't do anything.

---

Same origin policy

<> Same Origin Policy & Fetch requests
<> Same Origin Policy & iframe

---

Do guides need to generate their own codelab links?

In order to populate the codelabs sidebar:

And the codelabs cta's:

Should the author list something in the guide's YAML to indicate the associated codelabs? Or is there some other way we could generate this markup?

Profile: implement metrics table

With FCP, TTI, etc.

Gonna need help with code in tables!

Files like this one are nearly impossible to get going right: https://github.com/GoogleChrome/web.dev/blob/master/content/path/fast/serve-images-webp/index.md

Basically you want to have code in the html, but the

 tags aren't working. And then when you try and use markdown tables, it's a real nightmare to format.

Maybe it is as simple as supporting 
?

Understanding key performance metrics: visual to grok the different metrics

I wonder if the main image is a little hard to grok.

We are working on some video content for CDS to visualize the various metrics, and I wonder if that can be repurposed in the future to get an "a ha!" moment on TTI vs FID vs......

I wonder if here, or in the "verticals" content, we can talk about the difference in priority of FCP++ vs. TTI/FID.

Duplicate "see it in action" sections on almost every guide

Measure page: problem when switching URL

1. Go to https://web.devsite.corp.google.com/profile
2. Click SWITCH URL and enter a new URL.

Result as per screenshot.

If you then click RUN AUDIT, the buttons are greyed out and nothing appears to happen for several seconds, i.e. there isn't any UI to show that an audit is being run.

AVERAGE IMPACT / COMPATIBILITY card is puzzling

I don't know what this means:

Is this feature complete?

Content feedback for understand-key-performance-metrics

Content: https://web.devsite.corp.google.com/path/fast/understand-key-performance-metrics

• First diagram has FMP and FCP as acronyms. If I am learning a topic, I expect to see all acronyms expanded upon first reference on a page. These acronyms were not expanded until later on the page.
• Under “Measuring in the lab” it says “Learn more at Discover performance opportunities with Lighthouse.” - I think the text should be italics and a URL link, similar to the "Learn more at" in the following paragraphs.

Change show-live images across the site

We've got the green show live button everywhere, and now it's pink.

I'll take this on to replace the show live images with new show live image.

Profile: audit element complains about missing css file

Not sure why it's trying to load a file. It's part of our non css bundles.

Lingering markup in code-splitting codelab

Very small lingering markup in code-splitting codelab.

http://skare.c.googlers.com:8080/path/fast/reduce-javascript-payloads-with-code-splitting/codelab-code-splitting?tenant=web

I can fix this one.

Learn page headings seem inconsistent

These are currently both verbs and nouns: Fast Load Times, Discover, Security, Install.

I think they might have more impact as all one or other. For example: Fast, Findable, Safe, Installable.

http://crobdodson.c.googlers.com:8080/learn?tenant=web

Codelab page links seem broken

Entirely possible I'm doing something wrong but this is what's generated in my build/

<a href="reduce-javascript-payloads-with-code-splitting/codelab-code-splitting" class="button button-flat">
      Start
    </a>

I think we just need to remove the guide name from the beginning part of the URL

Update screenshots, instructions on Glitch actions

With the new UI for the Glitch embed, there are a number of things that have changed. For example, the Show Live button does not look like this anymore:

But is situated at the bottom right and looks like this:

---

We may need update other screenshots as well (Console button, etc...)

Learn page: cards are different widths

At smaller viewport widths, the 'cards' on the Learn page are different widths, depending on the content.

Is that intentional?

http://crobdodson.c.googlers.com:8080/learn?tenant=web

Glitch embed app column no longer updates.

Not sure if anything changed recently but typing code into the Glitch editor no longer triggers an update in the app column. However, if you click the 'fullscreen' button and view your code on Glitch the changes show up over there. I hope this is a Glitch issue and not us doing anything weird. I'll follow up with the Glitch team tomorrow.

Speed up app remixes with webpack

Change the location of the webpack cache when booting up the app in package.json:

"scripts": { "start": "TMP=/app/.tmp webpack && ..." },

This should cut down the remix times

Footer is missing horizontal padding at larger viewport widths

There is padding in app.css for widths up to 840px, but not above that:

media screen and (max-width: 600px)
[ds-is="content-footer"] {
  padding: 0 16px;
}
@media screen and (max-width: 840px)
[ds-is="content-footer"] {
  padding: 0 24px;
}

Footer license note isn't accessible

I'd make a PR for this but I can't get the CSS to show up locally.

On /learn, the license information in the footer isn't accessible. In order for this to be compliant at this size, that font color needs to be made darker.

Changing the color slightly makes it AA accessible

Changing it to the same color as the devsite-content-footer component background actually makes it AAA accessible

Add a top-level directory for Glitch source

We'll need something like:

glitches/
  my-glitch-id/
  my-other-glitch-id/

That way authors can check-in their source and we can link back to glitch using a webhook.

Improve Codelab styles

• Remove h1 heading (we already have a title just above it).
  • This just means deleting the first heading in the codelab markdown files and making sure the YAML title is correct.
• Increase font-size to ~17px
• Increase line-height to ~1.5
• Make subheadings bold
• Create some framing around images so they don't seem like they're "floating"

If anyone is interested in doing some very light CSS editing in g3 I can show you how it's done :)

Need search page templates

I feel like I've been able to get the path, guide, and codelab pages to look close to our original designs. I think I'd like it if we just did similar custom HTML for the other pages so we can opt-out of the weird headers and whatnot that devsite adds.

Profile: Users that enter an URL for the first time shouldn't be able to see historical data for a URL that's already in the system.

e.g. It's a bit weird that you would come to a site you've never been to before and see data from the past.

I'll add support to the backend to filter based on a ?since param.

https://webdev-dot-lighthouse-ci.appspot.com/lh/reports?url=https://www.chromestatus.com/features&since=2018-10-18

Notes inside of a code block

"And import it within the event listener that fires when the button is pressed:" is in between two bits of code.

http://crobdodson.c.googlers.com:8080/path/fast/reduce-javascript-payloads-with-code-splitting/codelab-code-splitting?tenant=web

Build scripts should generate breadcrumb links

These things:

@TimvdLippe is this something you might be interested in working on?

Build step should have links for next guide and link back to all guides.

The bottom of each guide has this content:

Maybe for next guide we can pull from the guides.yaml?

Formatting for keyboard shortcuts

"Press Control+Shift+J or Command+Shift+J (Mac) to open DevTools."

I wonder if we should have a style for commands to have them be more called out?

Let users know that applications take some time to reload with webpack

With a working Glitch environment, any update to a file that should be edited reloads the application quickly:

If webpack is used, the build process takes a bit longer (~5-10s), and the only indication that the application is in the process of reloading is the tiny orb thing in the Status bar

Readers new to the environment may not realize this, so we probably need to mention this in the user setup instructions of the codelab.

Codelabs that use webpack:

• Reduce JavaScript payloads with code-splitting
• Reduce network payloads using text compression
• Remove unused code
• Serve modern code to modern browsers for faster page loads

Forgot to bring over text compression codelab from old GitHub repo!

Need to add the text compression codelab from old repo. Don't know how I missed this one!

Need to optimize images as part of the build

Here's where we slowly turn into a gulp file :P

I noticed some folks are checking in huge images because they're screenshotting their desktops. We probably need to resize those down to whatever our max image dimensions are and run them through an optimizer.

Content feedback for use-imagemin-to-compress-images

Content: https://web.devsite.corp.google.com/path/fast/use-imagemin-to-compress-images

• “(‘0' being the word; ‘100' being the best).” Change “word” to “worst”.

Activate sign into google buttons

These buttons need to open the sign in url. Not sure how devsite creates the "sign in" link in the nav but we need to create the same link.

listen on the body for CustomEventType.SIGNED_IN_STATE_CHANGED and the detail is {signedIn}

Content feedback for use-imagemin-to-compress-images/imagine-cli

Content: https://web.devsite.corp.google.com/path/fast/use-imagemin-to-compress-images/imagine-cli

• The sample Linux commands have a “copy” button in the corner, but it copies the “$” prompt as well, so you cannot paste the results into a shell to run the commands. In that case, I would not have a copy button. It’s not a code snippet. Otherwise remove the "$" symbol so its safe to copy and paste the Linux commands.
• Before running the command to minimize the images would have been nice to do an “ls -l images/*” (to see before/after file size comparison), plus run an Lighthouse audit first, so I could see the before and after image sizes. Now I have run the minimize command, I cannot tell by how much they were compressed.
• “Run the Lighthouse performance audit (Lighthouse > Options > Performance) on the live version of your Glitch and verify that the "Efficiently encode images" audit was passed.” - I don’t know what “Lighthouse > Options > Performance” is. I assume this is just out of date now and it is the "Audit" tab instead.
• “Foobar Flowershop” seems a strange name for Google to use. I would go with something a bit more upmarket - “Fantastic Flowershop”? Foobar can be confused with Fubar, which is inappropriate to use - because of what it expands to, but also because it indicates a failure.
• After compressing images, Lighthouse report still reports two opportunities for improvement, and both related to images - so it feels like compression failed to fully address the issues.
  • Serve images in next-gen formats 0.9 s
  • Efficiently encode images 0.45 s
• “You can run $imagemin --help to see other ways of using the CLI.” - Remove the “$” symbol, or at least put a space in there. You don't run "$imagemin" - the "$" is the shell prompt.
• “3 Run Grunt” - It said to run “grunt”, but it’s not in my file path in the console window, and I assume the images have already been compressed so will not compress further?
• At bottom of page it ends with “Let's customize our Imagemin configuration to yield bigger file size savings.” so I assume the page is not finished. There was no “go to next page” button.

Return to all guides: link doesn't seem to work

http://crobdodson.c.googlers.com:8080/path/discoverable/pass-lighthouse-seo-audit?tenant=web

Click on Return to all guides — you're just taken to the top of the page.

Incomplete title for "replace animated GIFs with" doc

The title just says "Replace animated GIFs with". With what? Also, there's a big empty space. Is there an image missing?

UI/UX on learning page could be more obvious

When I went to a learning page, I didn't know how to start.

I clicked the START button, but that just took me to the top of the page.

I eventually realised that you need to click on one of the topics.

Is this intentional? I think 'What can I do here?' could be clearer.

http://crobdodson.c.googlers.com:8080/path/discoverable?tenant=web

Heading case is inconsistent

Generally sentence case is used, but sometimes not.

For example: 'Fast Load Times' (throughout) and 'Understand Key Performance Metrics' (and other titles on the Fast Load Times page).

I think it would be better to standardise on sentence case everywhere.

Fix LH warnings for inefficient cache and next-gen images.

While on https://web.devsite.corp.google.com/path/fast/discover-performance-opportunities-with-lighthouse I ran the performance audit on the tutorial page itself, to try out the instructions on the page. It seemed the logical thing to do and I think others will do it as well. So that page needs to be fast so it is not embarrassing that our own page is not fast.

I got red marks for “images are not next gen format”. It also says “Uses inefficient cache policy on static assets”.

Need to review on final production site.

Not sure what "Mark as Completed" button does

I assume the "Mark as Completed" button is not implemented yet - it does not seem to do anything. But it does click (in out animation) - I expected the button to stay depressed to indicate it was now marked as complete. Noting this just in case.