deprecating window.guardian

[sndrs]

Putting page config on a global (window.guardian) is inherently brittle. Any code that runs on the page can change it however it likes.

It also means to meaningfully type it we have describe a platform global in a way we cannot guarantee to the consumer, thus breaking type safety (even if a prop is there we don't know for sure that its value is what we said it would be in the definition).

Proposal

• add a typed singleton object to @guardian/libs (env) that mimics current use of window.guardian
• replace all instances of accessing window.guardian with this object
• lint against accessing window directly
  • can be disabled where it will break functionality, for example with a 3rd party

Example

Implementation

type Env = {
    a?: {
        b: string
    }
    [key: string]: unknown // you don't _have_ to type what you store, but you can
}

declare global {
	interface Window {
		__env__?: Env // this is still flakey, but is there a way round it?
	}
}

// collect whatever the page has set for us
export const env: Env = Object.assign({}, window.__env__); 
delete window.__env__ ;

Usage

<script>
window.__env__ = {
	isModernBrowser: true, // etc
}
</script>

import { env } from '@guardian/libs';

const b = env.a?.b; // string | undefined

Issues

What if there are multiple instances of @guardian/libs on the page?

[sndrs]

window.__env__ might be too guessable, but you get the idea

[mxdvl]

Might the be a good use case for Symbol()?

[mxdvl]

I really like this idea. I think there should be automatic deprecation built-in if we are to prevent this from growing without end.

Would it be possible to have a set method so platforms can ensure that they are passing a valid configuration file in the first place?

[sndrs]

for use on the server do you mean? something like:

// pageHtml.tsx

import { hydrateEnvWith } from '@guardian/libs'

const env = hydrateEnvWith({
	config: {}, // fine
	// oewifowien: NaN – this would throw/type error
})
// initialEnv = 'window.__env__={config:{}}'

export const pageHtml = () => `
	<script>${env}</script>
`

[mxdvl]

Yes, exactly that. I would imagine that this is a generic function that takes in Env as its type parameter? Otherwise all the consumers would need to update a centralised environment definition inside @guardian/libs.

interface Env {
	config: {
        isDev: boolean;
    }
}

const env = hydrateEnvWith<Env>({
	config: { isDev: true },
})

[SiAdcock]

Since extracting the commercial bundle into its own executable script, @guardian/commercial-dev have been interested in ensuring we are not bundling dependencies that are already available in platform bundles, notably Raven, Ophan and potentially the AB testing framework.

Would @guardian/libs be a good place to store and access references to these dependencies?

// graun.standard.js
import raven from `raven-js`;
import { hydrateEnv } from '@guardian/libs';

hydrateEnv({
  raven
});

// commercial.bundle.js
import { env } from '@guardian/libs';

env.raven.captureException(error, { tags });

[SiAdcock]

Thanks @sndrs. For anyone reading, window.guardian.modules was introduced in guardian/dotcom-rendering#727

Federated modules is certainly a viable alternative to this proposal. I barely remember that @mxdvl might have done some investigation into Federated Modules. Did you get anywhere with that, Max? And write-ups or spikes would be useful background reading. Apologies if I'm mis-remembering 😅

[mxdvl]

I'll try to dig some notes up, but I failed to orchestrate the builds from frontend and DCR when I last played around.

I would much rather deal with native ESM than create yet another bind to Webpack.

What's this giving us that creating our own version of esm.sh/jsdelivr/skypack would not? https://dev.to/marais/webpack-5-and-module-federation-4j1i. Worth noting that we already ship immutable assets on assets.guim.co.uk, so we could easily plonk some static versions of specific libs in there, too.

[sndrs]

couple of things i can think of:

1. how do we ensure everyone is using the same version (and so loads the same file(s))?
   • import maps are not well supported and the shim is a 12kb download
2. what do we do for browsers that don't support es modules (currently still supported)?

[mxdvl]

1. how do we ensure everyone is using the same version (and so loads the same file(s))?

I’m assuming that the version would be a fully qualified, immutable path – e.g. https://esm.sh/@guardian/libs@14.0.0 or even a specific build https://esm.sh/v116/@guardian/libs@14.0.0/es2022/libs.mjs

2. what do we do for browsers that don't support es modules (currently still supported)?

I’m assuming we can use the same mechanism that Wepback and other bunlders use for dynamic imports.

[sndrs]

I’m assuming that the version would be a fully qualified, immutable path

how do we guarantee two modules are importing a third using the same URL? e.g. i use 12.0.0 and you use 13.0.0 but we should both be using 14.0.0, how do we know?

I’m assuming we can use the same mechanism that Wepback and other bunlders use for dynamic imports.

if webpack downloads a module from a non-module bundle to a browser that doesn't understand them, what happens then?