We Upgraded Starwind Pro to Astro 7 and Cut the Full Build Pipeline by 64.7%

1
import { readdir, readFile, writeFile } from "node:fs/promises";
2
import { performance } from "node:perf_hooks";
3
import { fileURLToPath } from "node:url";
4
import path from "node:path";
5

6
import minifyHtml from "@minify-html/node";
7
import type { AstroIntegration } from "astro";
8

9
const { minify } = minifyHtml;
10

11
const ASTRO_COMMENT_TOKEN_PREFIX = "{{STARWIND_PROTECTED_ASTRO_COMMENT_";
12
const SOURCE_CODE_TOKEN_PREFIX = "{{STARWIND_PROTECTED_SOURCE_CODE_BLOCK_";
13
const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
14
const SOURCE_CODE_PATTERN =
15
  /<code\b(?=[^>]*\bdata-source-code(?:\s|=|>))[^>]*>[\s\S]*?<\/code\s*>/gi;
16
const MINIFY_OPTIONS = {
17
  keep_closing_tags: true,
18
  keep_html_and_head_opening_tags: true,
19
  keep_input_type_text_attr: true,
20
  minify_css: true,
21
  minify_js: true,
22
  preserve_brace_template_syntax: true,
23
} as const;
24

25
export interface HtmlMinifySummary {
26
  fileCount: number;
27
  beforeBytes: number;
28
  afterBytes: number;
29
  durationMs: number;
30
}
31

32
function isAstroFrameworkComment(comment: string) {
33
  const body = comment.slice(4, -3).trim();
34

35
  return /^\[if astro\]>/i.test(body) || /^astro(?::|$)/i.test(body);
36
}
37

38
function countOccurrences(source: string, search: string) {
39
  return source.split(search).length - 1;
40
}
41

42
function selectProtectionTokenPrefix(source: string, basePrefix: string) {
43
  let tokenPrefix = basePrefix;
44
  let suffix = 0;
45

46
  while (source.includes(tokenPrefix)) {
47
    tokenPrefix = `${basePrefix}${suffix++}_`;
48
  }
49

50
  return tokenPrefix;
51
}
52

53
function protectAstroFrameworkComments(source: string) {
54
  const tokenPrefix = selectProtectionTokenPrefix(
55
    source,
56
    ASTRO_COMMENT_TOKEN_PREFIX,
57
  );
58
  const comments: string[] = [];
59
  const protectedHtml = source.replace(HTML_COMMENT_PATTERN, (comment) => {
60
    if (!isAstroFrameworkComment(comment)) return comment;
61

62
    const token = `${tokenPrefix}${comments.length}}}`;
63
    comments.push(comment);
64
    return token;
65
  });
66

67
  return { comments, protectedHtml, tokenPrefix };
68
}
69

70
function restoreAstroFrameworkComments(
71
  source: string,
72
  comments: readonly string[],
73
  tokenPrefix: string,
74
) {
75
  let restoredHtml = source;
76

77
  for (const [index, comment] of comments.entries()) {
78
    const token = `${tokenPrefix}${index}}}`;
79
    const tokenCount = countOccurrences(restoredHtml, token);
80

81
    if (tokenCount !== 1) {
82
      throw new Error(
83
        `Rust HTML minification changed Astro framework comment token ${index}; expected it once, found ${tokenCount}.`,
84
      );
85
    }
86

87
    restoredHtml = restoredHtml.replace(token, comment);
88
  }
89

90
  if (restoredHtml.includes(tokenPrefix)) {
91
    throw new Error(
92
      "Rust HTML minification left an unresolved Astro framework comment token.",
93
    );
94
  }
95

96
  const restoredComments =
97
    restoredHtml.match(HTML_COMMENT_PATTERN)?.filter(isAstroFrameworkComment) ??
98
    [];
99
  if (
100
    restoredComments.length !== comments.length ||
101
    restoredComments.some((comment, index) => comment !== comments[index])
102
  ) {
103
    throw new Error(
104
      "Rust HTML minification did not restore Astro framework comments exactly.",
105
    );
106
  }
107

108
  return restoredHtml;
109
}
110

111
function protectSourceCodeBlocks(source: string) {
112
  const tokenPrefix = selectProtectionTokenPrefix(
113
    source,
114
    SOURCE_CODE_TOKEN_PREFIX,
115
  );
116
  const blocks: string[] = [];
117
  const protectedHtml = source.replace(SOURCE_CODE_PATTERN, (block) => {
118
    const token = `${tokenPrefix}${blocks.length}}}`;
119
    blocks.push(block);
120
    return token;
121
  });
122

123
  return { blocks, protectedHtml, tokenPrefix };
124
}
125

126
function restoreSourceCodeBlocks(
127
  source: string,
128
  blocks: readonly string[],
129
  tokenPrefix: string,
130
) {
131
  let restoredHtml = source;
132

133
  for (const [index, block] of blocks.entries()) {
134
    const token = `${tokenPrefix}${index}}}`;
135
    const tokenCount = countOccurrences(restoredHtml, token);
136

137
    if (tokenCount !== 1) {
138
      throw new Error(
139
        `Rust HTML minification changed source-code block token ${index}; expected it once, found ${tokenCount}.`,
140
      );
141
    }
142

143
    restoredHtml = restoredHtml.replace(token, block);
144
  }
145

146
  if (restoredHtml.includes(tokenPrefix)) {
147
    throw new Error(
148
      "Rust HTML minification left an unresolved source-code block token.",
149
    );
150
  }
151

152
  return restoredHtml;
153
}
154

155
async function findHtmlFiles(directory: string): Promise<string[]> {
156
  const entries = await readdir(directory, { withFileTypes: true });
157
  const nestedFiles = await Promise.all(
158
    entries.map(async (entry) => {
159
      const entryPath = path.join(directory, entry.name);
160

161
      if (entry.isDirectory()) return findHtmlFiles(entryPath);
162
      return entry.isFile() && entry.name.endsWith(".html") ? [entryPath] : [];
163
    }),
164
  );
165

166
  return nestedFiles.flat().sort();
167
}
168

169
/**
170
 * Minifies one generated HTML document while preserving Astro's framework control comments and
171
 * source-code examples exactly.
172
 */
173
export function minifyHtmlDocument(source: string) {
174
  const {
175
    blocks,
176
    protectedHtml: sourceCodeProtectedHtml,
177
    tokenPrefix: sourceCodeTokenPrefix,
178
  } = protectSourceCodeBlocks(source);
179
  const {
180
    comments,
181
    protectedHtml,
182
    tokenPrefix: astroCommentTokenPrefix,
183
  } = protectAstroFrameworkComments(sourceCodeProtectedHtml);
184
  const minifiedHtml = minify(
185
    Buffer.from(protectedHtml),
186
    MINIFY_OPTIONS,
187
  ).toString("utf8");
188
  const commentsRestoredHtml = restoreAstroFrameworkComments(
189
    minifiedHtml,
190
    comments,
191
    astroCommentTokenPrefix,
192
  );
193

194
  return restoreSourceCodeBlocks(
195
    commentsRestoredHtml,
196
    blocks,
197
    sourceCodeTokenPrefix,
198
  );
199
}
200

201
/**
202
 * Minifies every generated HTML file beneath an Astro output directory.
203
 */
204
export async function minifyHtmlDirectory(
205
  directory: URL | string,
206
): Promise<HtmlMinifySummary> {
207
  const directoryPath =
208
    directory instanceof URL ? fileURLToPath(directory) : directory;
209
  const files = await findHtmlFiles(directoryPath);
210
  const startedAt = performance.now();
211
  let beforeBytes = 0;
212
  let afterBytes = 0;
213

214
  await Promise.all(
215
    files.map(async (file) => {
216
      const source = await readFile(file, "utf8");
217
      const minified = minifyHtmlDocument(source);
218

219
      beforeBytes += Buffer.byteLength(source);
220
      afterBytes += Buffer.byteLength(minified);
221
      await writeFile(file, minified);
222
    }),
223
  );
224

225
  return {
226
    fileCount: files.length,
227
    beforeBytes,
228
    afterBytes,
229
    durationMs: performance.now() - startedAt,
230
  };
231
}
232

233
/**
234
 * Runs native Rust HTML, inline CSS, and inline JavaScript minification after Astro writes output.
235
 */
236
export function htmlMinify(): AstroIntegration {
237
  return {
238
    name: "starwind-html-minify",
239
    hooks: {
240
      "astro:build:done": async ({ dir, logger }) => {
241
        const summary = await minifyHtmlDirectory(dir);
242
        const removedMiB =
243
          (summary.beforeBytes - summary.afterBytes) / 1024 / 1024;
244

245
        logger.info(
246
          `Minified ${summary.fileCount} HTML files with Rust in ${(summary.durationMs / 1000).toFixed(2)}s, removing ${removedMiB.toFixed(2)} MiB.`,
247
        );
248
      },
249
    },
250
  };
251
}