Best practices for modern web development

  • By Google
  • Last update: Dec 30, 2022
  • Comments: 15

Web Fundamentals on DevSite

Build Status License

Welcome to the new Web Fundamentals! An effort to showcase best practices and tools for modern Web Development.

What's changed?

  • We're now using the DevSite infrastructure
    • New style guide
    • New widgets allow inline JavaScript, common links, related guide and more
  • Jekyll has been eliminated. Instead, pages are rendered at request time
  • Front-matter has been eliminated from the markdown, but files now require a simple set of tags

What stays the same?

Cloning the repo

If you have a high-bandwidth connection, I recommend starting with a fresh clone of the repo.

git clone https://github.com/google/WebFundamentals.git

Getting set up

The new DevSite infrastructure simplifies the dependencies a lot. Ensure that you have Python, Node 10-12, and the Google Cloud SDK already installed.

Login to Google Cloud via command line.

  1. Run npm install (needed for the build process)

Building the auto-generated files

Some files (contributors includes, some pages for updates, showcases, etc.) are automatically generated. The first time you clone the repo and run npm install, this is done for you. However, when you add a case study, update, etc., you'll need to re-build those files using:

npm run build

Starting Local Server

To view the site locally, just run:

npm start

Note: The first time you start the server, you may need to run start-appengine.sh and answer any prompts provided by dev_appserver.py.

Updating the code labs

To update the Code Labs, you'll need the claat tool and access to the original Doc files. This will likely only work for Googlers.

  1. Download the claat tool and place it in your tools directory
  2. Run tools/update-codelabs.sh
  3. Check the latest changes into GitHub

Starting the development server

  1. Run npm start in the terminal.

Testing your changes before submitting a PR

Please run your changes through npm test before submitting a PR. The test looks for things that may cause issues with DevSite and tries to keep our content consistent. It's part of the deployment process, so PRs will fail if there are any errors! To run:

npm test

Github

https://github.com/google/WebFundamentals

Comments(15)

  • 1

    Add new Understanding Resource Timing documentation.

    Adding a new page specifically for resource timing. Moving the data from the existing network page to it and expanding upon it.

    Sorry @kaycebasques, you know I can't test locally. So please let me know what is needed to make sure this is linked properly from places like the DevTools landing page's Network tab. If it isn't automatically done.

  • 2

    Web Performance Optimization with webpack

    What's changed, or what was fixed?

    • Added an article on front-end performance with webpack

    Target Live Date: Probably January?

    • [x] This has been reviewed and approved by @addyosmani
    • [x] I have run gulp test locally and all tests pass. (There’re a few <script>-related warnings, but these <script> blocks are code examples)
    • [x] I have added the appropriate type-something label. (Not sure what’s this and haven’t found related info)
    • [x] I've staged the site and manually verified that my content displays correctly.

    R: @petele

    I also have a few formatting-related questions:

    1. For some reason, “Note:” blocks were recognized during one server launch and weren’t recognized during another. Probably that’s my local buggy installation, but IDK. Could we check this on the proper environment?

    2. Locally, {: .hide-from-toc } wasn’t hiding “Further reading” headers from TOC (see e.g. decrease-frontend-size.md. Could you please check if I’m using them properly?

    3. Is there a way to enable diff-like formatting (see below) for specific code blocks? I use it in a few code examples.

    - const a = 5;
+ const b = 5;
    1. I’d like to add “Next section” arrows like in “Optimizing Content Efficiency”. How to I do this? I haven’t found any related markup, and the “Optimizing Content Efficiency” article in my local build didn’t have them.

    image

  • 3

    Added "How to Think About Speed Tools" article.

    This PR contains new content mocked up for /web in the performance section entitled "How to Think About Speed Tools" requested by @addyosmani.

  • 4

    Webpack guide updates for webpack 4

    What's changed, or what was fixed?

    • Updated the guide for webpack 4
    • Fixed a few wording/formatting issues

    Target Live Date: 2018-02-24 (webpack 4 release)

    • [x] This has been reviewed and approved by (Addy)
    • [x] I have run gulp test locally and all tests pass. (I’m on windows, and it’s hard here, sorry.)
    • [X] I have added the appropriate type-something label.
    • [x] I've staged the site and manually verified that my content displays correctly.

    Please don’t merge this yet. I was unable to test some plugins with webpack 4 because they weren’t made compatible yet. Here’s what left to do:

    • [x] Test the InlineChunkWebpackPlugin instructions and update them if necessary
    • [x] Test the WebpackManifestPlugin instructions and update them if necessary

    I’ll re-check the status of these plugins on the next week.

    Feel free to review the remaining text meanwhile, it should be stable.

    CC: @petele @addyosmani

  • 5

    [Translation it] Performance > Optimizing content efficiency > Automating-image-optimization

  • 6

    Add media video preload article

    This is my WIP (not ready at all) article for video preload. Let's use it to get feedback.

    Live preview at https://pr-4744-dot-web-central.appspot.com/web/fundamentals/media/fast-playback-with-video-preload

  • 7

    Update guidance on RAIL

    What's changed, or what was fixed?

    This is an update to our RAIL guidance including affordances for our newer loading metrics. It also introduces a more explicit call out for goals and guidelines for each area.

    The goals and guidelines call outs are something the Chrome Speed Metrics team felt would make for a more clear framing of RAIL.

    Fixes: #5464 with more details on what changed

    Target Live Date: December 15th

    • [ X] I have run gulp test locally and all tests pass.
    • [ X] I have added the appropriate type-something label.

    R: @petele @Meggin @kaycebasques

    Notes: This is my last day in the office for this year. If anyone would like to take on directly editing/addressing further changes before the new year, I'm more than happy for them to do so :)

  • 8

    Make the homepage look more like the documentation page

    • Reduce the height and prominent of the link to "Get Started"
    • Include links to articles within sections
    • Use the card layout design that's currently on the documentation page
  • 9

    Feedback for: /fundamentals/getting-started/web-starter-kit/setting-up.html

    Under the Sass section you say that once you install Gulp globally that Sass will be available to you. I am pretty sure that the gulp-ruby-sass still relies on ruby and sass, so you still need to install ruby and sass separately for Windows Os. Otherwise nice articles!

    See gulp-ruby-sass page

  • 10

    [EN] Feedback for: /web/tools/chrome-devtools/profile/evaluate-performance/performance-reference?hl=en

    It seems that the following guides:

    Are completely out of date, as far as I can tell. The Timeline view that I have in Version 47.0.2526.80 (64-bit) looks like: screen shot 2015-12-11 at 8 51 39 am

    Which doesn't seem to correspond at all to the view those articles use:

    image

    It wouldn't be a big deal if it was just a small UI update, but it seems that the feature set described in those articles have been replaced, or at least obscured. Things like Events/Frames mode seem to be gone, and I can't find any newer posts with updated information on the Timeline view.

    At the very least, if there is a post I'm missing, this article should note that the view is out of date.

  • 11

    Localization Support: Quick questions before translating WebFundamentals

    Hi

    I just try to translate WebFundamentals into Korean with some developers, and have some quick questions before diving it. :)

    Q. Is it possible to commit translated pages one by one?

    For example, when I translated article in HTML5Rocks, I added the directory 'ko' in same level of place of source tree, and then translated it. If users visit an article without its translation, H5R shows a sorry message and delivery its default version. I think that it's available at WebFundamentals as I can see from Translation Guide. I just want to confirm it again before arranging our translation plan. :)

    Q. How can we track changes of documents?

    WebFundamentals' articles have been updating frequently. This means translator have to track these changes like below:

    1. Being aware of update.
    2. Finding the latest source version of translation.
    3. Comparing it and its new history for knowing where it have been changed.
    4. Updating translations.
    5. Repeat these works.

    Suggestion: support workflow tools for translation

    I think the most simple solution is that adding current source hash to the translation. However, human can take mistakes easily, I hope some utilities for initialization of translation and searching out-dated documents like below:

    Initializing structure or page for the translation

    Before translating article(s), Translator initialize structure or page. I guess this can be ignored on working process. I just suggest this to avoid copying unnecessary resources.

    $ translate _en/fundamentals/getting-started/your-first-multi-screen-site/ -l ko
Create files at _ko/fundamentals/getting-started/your-first-multi-screen-site/
[1] content.markdown
[2] index.markdown
[3] responsive.markdown
    Finding outdated translations
    $ find-outdated -l ko
Find 1 outdated translation(s)...

[1] _ko/fundamentals/getting-started/your-first-multi-screen-site/index.markdown
Source: _en/fundamentals/getting-started/your-first-multi-screen-site/index.markdown
Latest source version: 3a4e67bf - 7 commit(s) after translation
...

    Then translator can update the translation according to its history.

    Update hashes

    This will add the version of source hash to the translation, when translator want to update it.

    $ update-hash _ko/fundamentals/getting-started/your-first-multi-screen-site/
Update hash information in translations...

[1] content.markdown has updated as 1286eab3 of _en/fundamentals/getting-started/your-first-multi-screen-site/content.markdown
[2] index.markdown has updated as 3a4e67bf of _en/fundamentals/getting-started/your-first-multi-screen-site/index.markdown

    Then commit translation and send Pull Request or Update hash before update.

    Of course, above things are just sketchy imaginations. If you have any suggestion, It helps us. Thanks. :)

  • 12

    [Remote Debugging]

    Welcome! Please use this template for reporting documentation issues on https://developers.google.com/web/.

    For questions about Chrome DevTools, checkout the google-chrome-devtools tag on StackOverflow. For questions about Chrome, check the google-chrome tag. If you think you've found a Chrome bug, check out our feedback page for more details on how to file it.

    Page Affected: https://developers.google.com/web/TODO

    What needs to be done?

    Please provide description of what's needs to be done here. Please be sure to include the link to the original page and any supporting links/data.

    • [ ] Appropriate type-something label has been added.
    • [ ] Appropriate section-something label has been added.
  • 13

    [Remote Debugging]

    Welcome! Please use this template for reporting documentation issues on https://developers.google.com/web/.

    For questions about Chrome DevTools, checkout the google-chrome-devtools tag on StackOverflow. For questions about Chrome, check the google-chrome tag. If you think you've found a Chrome bug, check out our feedback page for more details on how to file it.

    Page Affected: https://developers.google.com/web/TODO

    What needs to be done?

    Please provide description of what's needs to be done here. Please be sure to include the link to the original page and any supporting links/data.

    • [x] Appropriate type-something label has been added.
    • [x] Appropriate section-something label has been added.
  • 14

    Verbal fix on documentation's blue "activation" note section

    Page Affected: https://developers.google.com/web/ilt/pwa/introduction-to-service-worker#activation

    What needs to be done?

    Typo fix on blue "activation" note section: Remove the double the on sentence: ... because the new page will be requested before the the current page is unloaded ...

    image
  • 15

    PageSpeed Insights can't realize CSS Cascade Layers.

    Hi,

    I use PageSpeed Insights to check web page. I found my CLS score is ugly then I realize CSS losing (from preview). I use CSS Cascade Layers for web page. I wonder can't PageSpeed Insights realize CSS Cascade Layers ?

    image

    Here comes my style code.

    <style>
@layer reset, defaults, patterns, components, utilities, overrides;

@import url('css/auction/reset.css') layer(reset.reset);
@import url('css/auction/defaults.css') layer(defaults.vars);
@import url('css/auction/header.css') layer(components.header);
@import url('css/auction/footer.css') layer(components.footer);
@import url('css/auction/buttons.css') layer(components.buttons);
@import url('css/auction/carousel.css') layer(components.carousel);
@import url('css/auction/shortcuts.css') layer(components.shortcuts);
@import url('css/auction/heros.css') layer(components.heros);
</style>

    Thank you for reading.

Popular Tag

Related