Preload

W3C Candidate Recommendation

This version:
https://www.w3.org/TR/2017/CR-preload-20171026/
Latest published version:
https://www.w3.org/TR/preload/
Latest editor's draft:
https://w3c.github.io/preload/
Previous version:
https://www.w3.org/TR/2017/WD-preload-20170830/
Editors:
Ilya Grigorik, Google,
Yoav Weiss, Akamai,
Test suite:
http://w3c-test.org/preload/
Implementation report:
https://wpt.fyi/preload
Participate:
GitHub w3c/preload
File a bug
Commit history

Abstract

This specification defines the preload keyword that may be used with link elements. This keyword provides a declarative fetch primitive that initiates an early fetch and separates fetching from resource execution.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Performance Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. Comments regarding this document are welcome. Please send them to public-web-perf@w3.org (subscribe, archives) with [preload] at the start of your email's subject, or file a GitHub issue. W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 23 November 2017.

The Group expects to demonstrate at least 2 implementations of all the features in this specification. There are no features at risk and significant change since the previous publication.

Please see the Working Group's implementation report.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

1. Dependencies

The terms link, match the environment, inserted into a document, url, crossorigin, origin, delay the load event, external resource link, valid media query list, queue a task and obtain the resource are defined in [HTML52].

The terms Document, Content-Type metadata, fire an event , in a document tree and node document are defined in [DOM41].

The term request destination is defined in [FETCH].

The terms parsable MIME type and unsupported MIME type are defined in [MIMESNIFF].

The term prefetch is defined in [RESOURCE-HINTS].

2. Introduction

Many applications require fine-grained control over when resources are fetched, processed, and applied to the document. For example, the loading and processing of some resources may be deferred by the application to reduce resource contention and improve performance of the initial load. This behavior is typically achieved by moving resource fetching into custom resource loading logic defined by the application - i.e. resource fetches are initiated via injected elements, or via XMLHttpRequest, when particular application conditions are met.

However, there are also cases where some resources need to be fetched as early as possible, but their processing and execution logic is subject to application-specific requirements - e.g. dependency management, conditional loading, ordering guarantees, and so on. Currently, it is not possible to deliver this behavior without a performance penalty.

The preload keyword on link elements provides a declarative fetch primitive that addresses the above use case of initiating an early fetch and separating fetching from resource execution. As such, preload keyword serves as a low-level primitive that enables applications to build custom resource loading and execution behaviors without hiding resources from the user agent and incurring delayed resource fetching penalties.

For example, the application can use the preload keyword to initiate early, high-priority, and non-render-blocking fetch of a CSS resource that can then be applied by the application at appropriate time:

Example 1: Using markup
<!-- preload stylesheet resource via declarative markup -->
<link rel="preload" href="/styles/other.css" as="style">

<!-- or, preload stylesheet resource via JavaScript -->
<script>
var res = document.createElement("link");
res.rel = "preload";
res.as = "style";
res.href = "styles/other.css";
document.head.appendChild(res);
</script>
Example 2: Using HTTP Header

As above examples illustrate, the resource can be specified via declarative markup, Link HTTP header ([RFC5988]), or scheduled via JavaScript. See use cases section for more hands-on examples of how and where preload can be used.

4. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST NOT, and SHOULD are to be interpreted as described in [RFC2119].

There is only one class of product that can claim conformance to this specification: a user agent.

A. Use cases

This section is non-normative.

A.1 Early fetch of critical resources

Preload parsers are used by most user agents to initiate early resource fetches while the main document parser is blocked due to a blocking script. However, the preload parsers do not execute JavaScript, and typically only perform a shallow parse of CSS, which means that the fetch of resources specified within JavaScript and CSS is delayed until the relevant document parser is able to process the resource declaration.

In effect, most resources declarations specified within JavaScript and CSS are "hidden" from the speculative parsers and incur a performance penalty. To address this, the application can use a preload link to declaratively specify which resources the user agent must fetch early to improve page performance:

Example 4: Early fetch of critical resources

Above markup initiates four resource fetches: a font resource, a stylesheet, an unknown resource type from another origin, and a font resource from another origin. Each fetch is initialized with appropriate request headers and priority - the unknown type is equivalent to a fetch initiated XMLHttpRequest request. Further, these requests do not block the parser or the load event.

Note

Preload links for CORS enabled resources, such as fonts or images with a crossorigin attribute, must also include a crossorigin attribute, in order for the resource to be properly used.

A.2 Early fetch and application defined execution

The preload link can be used by the application to initiate early fetch of one or more resources, as well as to provide custom logic for when and how each response should be applied to the document. The application may:

The preload link provides a low-level and content-type agnostic primitive that enables applications to build custom resource loading and execution behaviors without incurring the penalty of delayed resource loading.

For example, preload link enables the application to provide async and defer like semantics, which are only available on script elements today, but for any content-type: applying the resource immediately after it is available provides async functionality, whereas adding some ordering logic enables defer functionality. Further, this behavior can be defined across a mix of content-types - the application is in full control over when and how each resource is applied.

Example 5
<script>
  function preloadFinished(e) { ... }
  function preloadError(e)  { ... }
</script>
<!-- listen for load and error events -->
<link rel="preload" href="app.js" as="script" onload="preloadFinished()" onerror="preloadError()">

By decoupling resource fetching from execution, the preload link provides a future-proof primitive for building performant application specific resource loading strategies.

A.3 Developer, server, and proxy-initiated fetching

The preload link can be specified by the developer, or be automatically generated by the application server or an optimization proxy (e.g. a CDN).

Example 6
Example 7
<link rel="preload" href="//example.com/widget.html" as="document">
Example 8
<script>
var res = document.createElement("link");
res.rel = "preload";
res.as = "document";
res.href = "/other/widget.html";
document.head.appendChild(res);
</script>

B. IANA Considerations

The link relation type below has been registered by IANA per Section 6.2.1 of [RFC5988]:

Relation Name:
preload
Description:
Refers to a resource that should be loaded early in the processing of the link's context, without blocking rendering.
Reference:
W3C Preload Specification (https://www.w3.org/TR/preload/)
Note:
Additional target attributes establish the detailed fetch properties of the link.

C. Privacy and Security

This section is non-normative.

Preload is a declarative fetch primitive that initiates early fetch of resources and separates fetching from resource execution. In effect, it is conceptually similar to initiating a scripted fetch for a resource, but with additional constraints and benefits:

The site authors are encouraged to take the necessary precautions and specify the relevant [CSP3], [MIXED-CONTENT], and [REFERRER-POLICY] rules, such that the browser can enforce them when initiating the preload request. Additionally, if preload directives are provided via the Link HTTP response header, then the relevant policies should also be delivered as an HTTP response header - e.g. see Processing Complications for CSP.

D. Acknowledgments

This section is non-normative.

This document reuses text from the [HTML] specification, edited by Ian Hickson, as permitted by the license of that specification.

E. References

E.1 Normative references

[CSP3]
Content Security Policy Level 3. Mike West. W3C. 13 September 2016. W3C Working Draft. URL: https://www.w3.org/TR/CSP3/
[DOM41]
W3C DOM 4.1. Yongsheng Zhu. W3C. 25 October 2017. W3C Working Draft. URL: https://www.w3.org/TR/dom41/
[FETCH]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML52]
HTML 5.2. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo; Sangwhan Moon. W3C. 8 August 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/html52/
[MIMESNIFF]
MIME Sniffing Standard. Gordon P. Hemsley. WHATWG. Living Standard. URL: https://mimesniff.spec.whatwg.org/
[MIXED-CONTENT]
Mixed Content. Mike West. W3C. 2 August 2016. W3C Candidate Recommendation. URL: https://www.w3.org/TR/mixed-content/
[REFERRER-POLICY]
Referrer Policy. Jochen Eisinger; Emily Stark. W3C. 26 January 2017. W3C Candidate Recommendation. URL: https://www.w3.org/TR/referrer-policy/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC5988]
Web Linking. M. Nottingham. IETF. October 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5988
[RFC7540]
Hypertext Transfer Protocol Version 2 (HTTP/2). M. Belshe; R. Peon; M. Thomson, Ed.. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7540

E.2 Informative references

[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RESOURCE-HINTS]
Resource Hints. Ilya Grigorik. W3C. 4 May 2017. W3C Working Draft. URL: https://www.w3.org/TR/resource-hints/