:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { CHUNK_CSS_GLOBAL } from '@posthog/esbuilder/cssLoader.mjs'
import { BOOT_ENTRIES, ENTRY } from './bootEntries.mjs'
import { alphanumericStem, chunkIdentity, shortHash } from './stableChunkNames.mjs'
/**
* Split stylesheets for the stable build.
*
* esbuild puts the CSS of every chunk, lazy ones included, into the entry's stylesheet, so every
* page downloads and parses all of the app's CSS before its first render. This step splits the
* same CSS into groups and builds each group as its own stylesheet, named by its own content:
*
* - Eager layers hold the CSS that the boot chain (entry, App, bootApp, AuthenticatedShell) imports
* statically. The stable page links them in order before the first render.
* - Lazy groups hold the rest, grouped by the JS chunks whose modules import it. A lazy entry
* chunk registers the groups its static imports need, and its import waits for them (see `cssPrelude`).
*
* Groups keep today's rule order among themselves, because every group lists its files in the
* order of the entry stylesheet. Lazy groups load after the eager layers.
*/
export const CSS_SPECIFIER_PREFIX = '@css/'
export function cssGroupFileStem(groupName) {
return alphanumericStem(`styles-${groupName}`)
}
const isStylesheet = (file) => /\.(css|scss|sass)$/.test(file)
function eagerLayer(file) {
if (file.endsWith('tailwind/tailwind.css')) {
return 'eager-tailwind'
}
if (file.endsWith('src/styles/global.scss')) {
return 'eager-global'
}
return 'eager-app'
}
const EAGER_ORDER = ['eager-tailwind', 'eager-global', 'eager-app']
/**
* Plans the groups from the app build's metafile. Pure.
*
* Returns `groups` (name -> source files in rule order), `eager` (layer names in link order) and
* `lazyGroupsByEntry` (lazy entry output path -> the lazy groups its static imports need).
*/
export function planCssGroups({ inputs, outputs }, bootEntries = BOOT_ENTRIES) {
const entryOutput = (entryPoint) =>
Object.keys(outputs).find((file) => outputs[file].entryPoint === entryPoint && file.endsWith('.js'))
const linkedStylesheet = outputs[entryOutput(ENTRY)]?.cssBundle
if (!linkedStylesheet) {
throw new Error('stable css: the entry has no stylesheet to split')
}
const linkedStylesheetInputs = outputs[linkedStylesheet].inputs
const order = Object.keys(linkedStylesheetInputs)
const rank = new Map(order.map((file, index) => [file, index]))
const boot = new Set(bootEntries.filter((entry) => inputs[entry]))
for (const queue = [...boot]; queue.length; ) {
for (const imported of inputs[queue.shift()].imports || []) {
if (imported.kind === 'import-statement' && inputs[imported.path] && !boot.has(imported.path)) {
boot.add(imported.path)
queue.push(imported.path)
}
}
}
const outputOfInput = new Map()
for (const [file, output] of Object.entries(outputs)) {
if (file.endsWith('.js')) {
for (const input of Object.keys(output.inputs)) {
outputOfInput.set(input, file)
}
}
}
const ownersOfStylesheet = new Map()
for (const [file, input] of Object.entries(inputs)) {
for (const imported of input.imports || []) {
if (isStylesheet(imported.path) && outputOfInput.has(file)) {
const owners = ownersOfStylesheet.get(imported.path) ?? new Set()
owners.add(outputOfInput.get(file))
ownersOfStylesheet.set(imported.path, owners)
}
}
}
const groups = new Map()
const groupsOfChunk = new Map()
// A lazy group is a run of adjacent files with the same owners, so it holds its rules in the
// same order as the entry stylesheet. Merging non-adjacent files would move the rules of the
// files between them. A run is named by its owners' identities, which do not change when code
// does, and by its first file, so a file added elsewhere does not rename it.
let previousOwnersKey = null
let runName = null
for (const file of order) {
let name
if (boot.has(file)) {
name = eagerLayer(file)
previousOwnersKey = null
} else {
const owners = [...(ownersOfStylesheet.get(file) ?? [])]
const ownersKey = owners
.map((owner) => chunkIdentity(outputs[owner]))
.sort()
.join('\n')
if (ownersKey !== previousOwnersKey) {
runName = `lazy-${shortHash(`${ownersKey}\n${file}`)}`
previousOwnersKey = ownersKey
}
name = runName
for (const owner of owners) {
const names = groupsOfChunk.get(owner) ?? new Set()
names.add(name)
groupsOfChunk.set(owner, names)
}
}
groups.set(name, [...(groups.get(name) ?? []), file])
}
// The layers link in EAGER_ORDER, which only matches the cascade while the boot stylesheets come
// in that order in the entry stylesheet. Fail the build rather than reorder rules silently.
const layerIndexes = order.filter((file) => boot.has(file)).map((file) => EAGER_ORDER.indexOf(eagerLayer(file)))
if (layerIndexes.some((index, i) => i > 0 && index < layerIndexes[i - 1])) {
throw new Error('stable css: boot stylesheets are not in layer order, so splitting them would reorder rules')
}
const firstRank = (name) => rank.get(groups.get(name)[0])
const lazyGroupsByEntry = new Map()
const bootOutputs = new Set(bootEntries.map(entryOutput))
for (const [file, output] of Object.entries(outputs)) {
if (!file.endsWith('.js') || !output.entryPoint || bootOutputs.has(file)) {
continue
}
const needed = new Set()
const seen = new Set([file])
for (const queue = [file]; queue.length; ) {
const current = queue.shift()
for (const name of groupsOfChunk.get(current) ?? []) {
needed.add(name)
}
for (const imported of outputs[current].imports || []) {
if (imported.kind === 'import-statement' && outputs[imported.path] && !seen.has(imported.path)) {
seen.add(imported.path)
queue.push(imported.path)
}
}
}
if (needed.size) {
lazyGroupsByEntry.set(
file,
[...needed].sort((a, b) => firstRank(a) - firstRank(b))
)
}
}
const eager = EAGER_ORDER.filter((name) => groups.has(name))
if (lazyGroupsByEntry.size > 0 && eager.length === 0) {
throw new Error('stable css: lazy chunks need split CSS but no eager layer would define the loader')
}
// Each group's place in the entry stylesheet, so the loader can keep lazy groups in that order
// whatever order scenes load them in.
const rankOfGroup = new Map([...groups.keys()].map((name) => [name, firstRank(name)]))
const bytesOfGroup = new Map(
[...groups].map(([name, files]) => [
name,
files.reduce((sum, file) => sum + linkedStylesheetInputs[file].bytesInOutput, 0),
])
)
return { groups, eager, lazyGroupsByEntry, rankOfGroup, bytesOfGroup }
}
/**
* The CSS bytes a stable page downloads before the given entry chunks run: the eager layers plus
* the lazy groups those entries wait for. A group holds the same CSS as its files do in the entry
* stylesheet, so their sizes there are its size, apart from the source-map comment each file ends with.
*/
export function stableCssBytes({ eager, lazyGroupsByEntry, bytesOfGroup }, entryOutputs) {
const names = new Set([...eager, ...entryOutputs.flatMap((entry) => lazyGroupsByEntry.get(entry) ?? [])])
return [...names].reduce((sum, name) => sum + bytesOfGroup.get(name), 0)
}
/**
* The line a lazy entry chunk starts with: it registers the chunk's stylesheets for
* `window.ESBUILD_IMPORT` to wait on. Without `import.meta.resolve` (Chromium 89 to 104 has import
* maps but not this) it registers `null`, which asks for the full stylesheet instead.
*/
export function cssPrelude(specifier, groupNames, rankOfGroup) {
const entries = groupNames.map(
(name) => `[import.meta.resolve(${JSON.stringify(CSS_SPECIFIER_PREFIX + name)}),${rankOfGroup.get(name)}]`
)
return `window.${CHUNK_CSS_GLOBAL}[${JSON.stringify(specifier)}]=typeof import.meta.resolve=="function"?[${entries.join(',')}]:null;`
}