extension-create 4.1.11 → 4.1.13

package/dist/lib/messages.d.ts

@@ -1,8 +1,9 @@
+import { type ScaffoldPackageManager } from './package-manager';
 export declare function destinationNotWriteable(workingDir: string): string;
 export declare function directoryHasConflicts(projectPath: string, conflictingFiles: string[]): Promise<string>;
 export declare function noProjectName(): string;
 export declare function noUrlAllowed(): string;
-export declare function scaffoldReady(projectPath: string, projectName: string, depsInstalled: boolean): Promise<string>;
+export declare function scaffoldReady(projectPath: string, projectName: string, depsInstalled: boolean, packageManager?: ScaffoldPackageManager): Promise<string>;
 export declare function startingNewExtension(projectName: string): string;
 export declare function createDirectoryError(projectName: string, error: unknown): string;
 export declare function writingTypeDefinitions(projectName: string): string;
@@ -13,6 +14,7 @@ export declare function installingFromTemplateError(template: string, error: unk
 export declare function templateFetchTimedOut(templateName: string, ms: number): string;
 export declare function templateNotFoundInCatalog(templateName: string, error?: unknown): string;
 export declare function templateDownloadFailed(templateName: string, error: unknown): string;
+export declare function templateOfflineFallback(requestedTemplate: string, fallbackTemplate: string, error: unknown): string;
 export declare function removedStaleTemplateLockfiles(fileNames: string[]): string;
 export declare function initializingGitForRepository(projectName: string): string;
 export declare function initializingGitSkipped(projectName: string, reason: string): string;
@@ -39,3 +41,5 @@ export declare function writingGitIgnore(): string;
 export declare function writingReadmeMetaDataError(error: unknown): string;
 export declare function writingDirectoryError(error: unknown): string;
 export declare function cantSetupBuiltInTests(error: unknown): string;
+export declare function keepingExistingGitignore(projectName: string): string;
+export declare function existingRepositoryKept(projectName: string): string;

package/dist/lib/package-manager.d.ts

@@ -5,3 +5,6 @@ export declare function detectPackageManagerFromEnv(): NodePackageManager;
 export declare function isDenoRuntime(): boolean;
 export type ScaffoldPackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun' | 'deno';
 export declare function resolveScaffoldPackageManager(): ScaffoldPackageManager;
+export declare function resolveProjectPackageManager(projectPath: string): ScaffoldPackageManager;
+export declare function readPinnedPackageManager(projectPath: string): NodePackageManager | undefined;
+export declare function resolvePackageManagerSpec(projectPath: string, manager: ScaffoldPackageManager): string | undefined;

package/dist/module.cjs

@@ -117,6 +117,8 @@ new Set([
     'librewolf',
     'waterfox'
 ]);
+const external_node_child_process_namespaceObject = require("node:child_process");
+const external_node_fs_namespaceObject = require("node:fs");
 const external_prefers_yarn_namespaceObject = require("prefers-yarn");
 const NODE_PACKAGE_MANAGERS = [
     'pnpm',
@@ -138,6 +140,48 @@ function resolveScaffoldPackageManager() {
     if (isDenoRuntime()) return 'deno';
     return detectPackageManagerFromEnv();
 }
+function resolveProjectPackageManager(projectPath) {
+    if (isDenoRuntime()) return 'deno';
+    const pinned = readPinnedPackageManager(projectPath);
+    if (pinned) return pinned;
+    if (external_node_fs_namespaceObject.existsSync(external_node_path_namespaceObject.join(projectPath, 'pnpm-workspace.yaml'))) return 'pnpm';
+    return detectPackageManagerFromEnv();
+}
+function readPinnedPackageManager(projectPath) {
+    try {
+        const raw = external_node_fs_namespaceObject.readFileSync(external_node_path_namespaceObject.join(projectPath, 'package.json'), 'utf8');
+        const pin = String(JSON.parse(raw)?.packageManager || '');
+        const name = pin.split('@')[0].toLowerCase();
+        return NODE_PACKAGE_MANAGERS.includes(name) ? name : void 0;
+    } catch  {
+        return;
+    }
+}
+function resolvePackageManagerSpec(projectPath, manager) {
+    if ('deno' === manager) return;
+    try {
+        const raw = external_node_fs_namespaceObject.readFileSync(external_node_path_namespaceObject.join(projectPath, 'package.json'), 'utf8');
+        const pin = String(JSON.parse(raw)?.packageManager || '');
+        if (pin.toLowerCase().startsWith(`${manager}@`)) return pin;
+    } catch  {}
+    const fromEnv = (0, external_prefers_yarn_namespaceObject.getPackageManagerSpec)();
+    if (fromEnv && fromEnv.startsWith(`${manager}@`)) return fromEnv;
+    try {
+        const version = (0, external_node_child_process_namespaceObject.execFileSync)(manager, [
+            '--version'
+        ], {
+            encoding: 'utf8',
+            stdio: [
+                'ignore',
+                'pipe',
+                'ignore'
+            ],
+            timeout: 5000,
+            shell: 'win32' === process.platform
+        }).trim().replace(/^v/, '');
+        if (/^\d+\.\d+\.\d+/.test(version)) return `${manager}@${version}`;
+    } catch  {}
+}
 function destinationNotWriteable(workingDir) {
     const workingDirFolder = external_node_path_namespaceObject.basename(workingDir);
     return `${prefix('error')} Couldn't write to the destination directory.\n${fmt.label('PATH')} ${fmt.val(workingDirFolder)}\n${external_pintor_default().red('Choose a writable path, or update the folder permissions.')}`;
@@ -155,9 +199,9 @@ function noProjectName() {
 function noUrlAllowed() {
     return `${prefix('error')} A URL is not a valid project path.\n${external_pintor_default().red('Pass a project name or a local directory path.')}`;
 }
-async function scaffoldReady(projectPath, projectName, depsInstalled) {
+async function scaffoldReady(projectPath, projectName, depsInstalled, packageManager) {
     const relativePath = external_node_path_namespaceObject.relative(process.cwd(), projectPath);
-    const pm = resolveScaffoldPackageManager();
+    const pm = packageManager ?? resolveScaffoldPackageManager();
     let command = 'npm run dev';
     let installCmd = 'npm install';
     switch(pm){
@@ -217,6 +261,9 @@ function templateNotFoundInCatalog(templateName, error) {
 function templateDownloadFailed(templateName, error) {
     return `${prefix('error')} Couldn't download the template ${external_pintor_default().blue(templateName)} from ${fmt.val('github.com/extension-js/examples')}.\n${fmt.label('REASON')} ${fmt.val(fmt.truncate(String(error?.message || error)))}\n${external_pintor_default().red('- Check your network connection and any GitHub rate limit, then try again.')}\n${external_pintor_default().red('- Set')} ${external_pintor_default().blue('EXTENSION_CREATE_TIMEOUT_MS')} ${external_pintor_default().red('to allow more time.')}`;
 }
+function templateOfflineFallback(requestedTemplate, fallbackTemplate, error) {
+    return `${prefix('info')} Couldn't download the template ${external_pintor_default().blue(requestedTemplate)} from ${fmt.val('github.com/extension-js/examples')}, so this scaffold uses the offline ${external_pintor_default().blue(fallbackTemplate)} template instead.\n${fmt.label('REASON')} ${fmt.val(fmt.truncate(String(error?.message || error)))}\n${external_pintor_default().gray('- Reconnect and run')} ${external_pintor_default().blue(`extension create --template ${requestedTemplate}`)} ${external_pintor_default().gray('to scaffold it.')}`;
+}
 function removedStaleTemplateLockfiles(fileNames) {
     return `${prefix('info')} Removed the template ${fileNames.map((name)=>fmt.val(name)).join(', ')}. The first install writes a fresh one.`;
 }
@@ -302,6 +349,12 @@ function writingDirectoryError(error) {
 function cantSetupBuiltInTests(error) {
     return `${prefix('error')} Couldn't set up the built-in tests.\n${fmt.label('REASON')} ${fmt.val(fmt.truncate(String(error)))}\n${external_pintor_default().red('The extension itself is fine. Re-run')} ${external_pintor_default().blue('extension create')}${external_pintor_default().red(', or skip the tests.')}`;
 }
+function keepingExistingGitignore(projectName) {
+    return `${prefix('info')} ${external_pintor_default().blue(projectName)} already has a ${external_pintor_default().blue('.gitignore')}.\nKeeping its rules and adding the template rules it lacks.`;
+}
+function existingRepositoryKept(projectName) {
+    return `${prefix('info')} ${external_pintor_default().blue(projectName)} is already a git repository with history.\nLeft it uncommitted. Review the scaffold and run ${external_pintor_default().blue('git add -A && git commit')} yourself.`;
+}
 const promises_namespaceObject = require("node:fs/promises");
 async function copyDirectoryWithSymlinks(source, destination) {
     const entries = await promises_namespaceObject.readdir(source, {
@@ -386,11 +439,13 @@ async function isDirectoryWriteable(directory, logger) {
 function isTypeScriptTemplate(templateName) {
     return templateName.includes("typescript") || templateName.includes('react') || templateName.includes('preact') || templateName.includes('svelte') || templateName.includes('solid');
 }
-const external_node_fs_namespaceObject = require("node:fs");
 const allowlist = [
     'LICENSE',
     'node_modules'
 ];
+const HIDDEN_FILES_TEMPLATES_SHIP = [
+    '.gitignore'
+];
 async function createDirectory(projectPath, projectName, logger) {
     logger.log(startingNewExtension(projectName));
     const directoryPreExisted = (0, external_node_fs_namespaceObject.existsSync)(projectPath);
@@ -409,6 +464,7 @@ async function createDirectory(projectPath, projectName, logger) {
             const conflictMessage = await directoryHasConflicts(projectPath, conflictingFiles);
             throw new Error(conflictMessage);
         }
+        for (const hidden of HIDDEN_FILES_TEMPLATES_SHIP)if (currentDir.includes(hidden)) logger.log(keepingExistingGitignore(projectName));
     } catch (error) {
         throw new Error(createDirectoryError(projectName, error));
     }
@@ -416,10 +472,67 @@ async function createDirectory(projectPath, projectName, logger) {
         directoryCreated: !directoryPreExisted
     };
 }
-async function generateExtensionTypes(projectPath, projectName, logger) {
-    const extensionEnvFile = external_node_path_namespaceObject.join(projectPath, 'extension-env.d.ts');
-    const typePath = 'extension';
-    const fileContent = `\
+const EXTENSION_ENV_TYPES_PACKAGE = 'extension';
+const STYLE_TYPE = 'Readonly<Record<string, string>>';
+const EXTENSION_ENV_WILDCARD_MODULES = Object.freeze([
+    {
+        pattern: '*.css',
+        type: STYLE_TYPE
+    },
+    {
+        pattern: '*.module.css',
+        type: STYLE_TYPE
+    },
+    {
+        pattern: '*.module.scss',
+        type: STYLE_TYPE
+    },
+    {
+        pattern: '*.module.sass',
+        type: STYLE_TYPE
+    },
+    {
+        pattern: '*.png',
+        type: 'string'
+    },
+    {
+        pattern: '*.jpg',
+        type: 'string'
+    },
+    {
+        pattern: '*.jpeg',
+        type: 'string'
+    },
+    {
+        pattern: '*.gif',
+        type: 'string'
+    },
+    {
+        pattern: '*.webp',
+        type: 'string'
+    },
+    {
+        pattern: '*.avif',
+        type: 'string'
+    },
+    {
+        pattern: '*.ico',
+        type: 'string'
+    },
+    {
+        pattern: '*.bmp',
+        type: 'string'
+    },
+    {
+        pattern: '*.svg',
+        type: 'any'
+    }
+]);
+function renderWildcardModuleDeclarations(modules = EXTENSION_ENV_WILDCARD_MODULES) {
+    return modules.map(({ pattern, type })=>`declare module '${pattern}' {\n  const content: ${type}\n  export default content\n}\n`).join('');
+}
+function renderExtensionEnvTypes(typePath = EXTENSION_ENV_TYPES_PACKAGE) {
+    return `\
 // Required Extension.js types for TypeScript projects.
 // This file is auto-generated and should not be excluded.
 // If you need additional types, consider creating a new *.d.ts file and
@@ -429,7 +542,15 @@ async function generateExtensionTypes(projectPath, projectName, logger) {
 
 // Polyfill types for browser.* APIs
 /// <reference types="${typePath}/types/polyfill" />
-`;
+
+// Asset and stylesheet imports. These wildcard declarations also live in
+// ${typePath}/types, but TypeScript 7 native does not apply them through the
+// reference above, so they are emitted here as well.
+${renderWildcardModuleDeclarations()}`;
+}
+async function generateExtensionTypes(projectPath, projectName, logger) {
+    const extensionEnvFile = external_node_path_namespaceObject.join(projectPath, 'extension-env.d.ts');
+    const fileContent = renderExtensionEnvTypes();
     try {
         await promises_namespaceObject.mkdir(projectPath, {
             recursive: true
@@ -489,6 +610,8 @@ const DEFAULT_TEMPLATES_REF = 'cb6a25377bd9516a1e55447a2010537019851ab2';
 const BUNDLED_TEMPLATES = [
     "javascript"
 ];
+const DEFAULT_TEMPLATE_NAME = "typescript";
+const OFFLINE_FALLBACK_TEMPLATE = "javascript";
 function resolveCatalogUrls(ref, overrideUrl) {
     if (overrideUrl) return [
         overrideUrl
@@ -640,6 +763,19 @@ async function withSuppressedOutput(task) {
 function bundledTemplateDir(templateName) {
     return external_node_path_namespaceObject.join(__dirname, '..', 'templates', templateName);
 }
+async function copyBundledTemplate(templateName, projectPath, logger, ownerGitignore = null) {
+    const localTemplate = bundledTemplateDir(templateName);
+    if (!(0, external_node_fs_namespaceObject.existsSync)(localTemplate)) return;
+    await copyDirectoryWithSymlinks(localTemplate, projectPath);
+    await restoreOwnerGitignore(projectPath, ownerGitignore);
+    await removeTemplateScaffoldingFiles(projectPath);
+    const dropped = await removeStaleTemplateLockfiles(projectPath);
+    if (dropped.length) logger.log(removedStaleTemplateLockfiles(dropped));
+    return {
+        template: templateName,
+        source: 'bundled'
+    };
+}
 const TEMPLATE_SCAFFOLDING_FILES = [
     'template.meta.json',
     'template.spec.ts',
@@ -711,6 +847,28 @@ async function cleanupFailedImport(projectPath, ownsProjectDir, preExistingEntri
             force: true
         }).catch(()=>{})));
 }
+async function readOwnerGitignore(projectPath) {
+    try {
+        return await promises_namespaceObject.readFile(external_node_path_namespaceObject.join(projectPath, '.gitignore'), 'utf8');
+    } catch  {
+        return null;
+    }
+}
+async function restoreOwnerGitignore(projectPath, ownerContents) {
+    if (null === ownerContents) return;
+    const target = external_node_path_namespaceObject.join(projectPath, '.gitignore');
+    let templateContents = '';
+    try {
+        templateContents = await promises_namespaceObject.readFile(target, 'utf8');
+    } catch  {
+        await promises_namespaceObject.writeFile(target, ownerContents);
+        return;
+    }
+    const ownerLines = new Set(ownerContents.split(/\r?\n/).map((line)=>line.trim()));
+    const added = templateContents.split(/\r?\n/).filter((line)=>line.trim().length > 0 && !ownerLines.has(line.trim()));
+    const merged = 0 === added.length ? ownerContents : `${ownerContents.replace(/\n?$/, '\n')}\n# Extension.js template rules\n${added.join('\n')}\n`;
+    await promises_namespaceObject.writeFile(target, merged);
+}
 async function importExternalTemplate(projectPath, projectName, template, logger, options) {
     const templateName = external_node_path_namespaceObject.basename(template);
     const resolvedTemplate = template;
@@ -724,22 +882,14 @@ async function importExternalTemplate(projectPath, projectName, template, logger
     if (dirExistedBeforeImport) try {
         preExistingEntries = await promises_namespaceObject.readdir(projectPath);
     } catch  {}
+    const ownerGitignore = dirExistedBeforeImport ? await readOwnerGitignore(projectPath) : null;
     try {
         await promises_namespaceObject.mkdir(projectPath, {
             recursive: true
         });
         if (!isHttp && !isGithub && BUNDLED_TEMPLATES.includes(resolvedTemplate)) {
-            const localTemplate = bundledTemplateDir(resolvedTemplate);
-            if ((0, external_node_fs_namespaceObject.existsSync)(localTemplate)) {
-                await copyDirectoryWithSymlinks(localTemplate, projectPath);
-                await removeTemplateScaffoldingFiles(projectPath);
-                const dropped = await removeStaleTemplateLockfiles(projectPath);
-                if (dropped.length) logger.log(removedStaleTemplateLockfiles(dropped));
-                return {
-                    template: resolvedTemplateName,
-                    source: 'bundled'
-                };
-            }
+            const provenance = await copyBundledTemplate(resolvedTemplate, projectPath, logger, ownerGitignore);
+            if (provenance) return provenance;
         }
         const tempRoot = await promises_namespaceObject.mkdtemp(external_node_path_namespaceObject.join(external_node_os_namespaceObject.tmpdir(), 'extension-js-create-'));
         const tempPath = external_node_path_namespaceObject.join(tempRoot, `${projectName}-temp`);
@@ -803,6 +953,7 @@ async function importExternalTemplate(projectPath, projectName, template, logger
                 } : {}
             };
         }
+        await restoreOwnerGitignore(projectPath, ownerGitignore);
         await removeTemplateScaffoldingFiles(projectPath);
         const droppedLockfiles = await removeStaleTemplateLockfiles(projectPath);
         if (droppedLockfiles.length) logger.log(removedStaleTemplateLockfiles(droppedLockfiles));
@@ -812,6 +963,17 @@ async function importExternalTemplate(projectPath, projectName, template, logger
         });
         return provenance;
     } catch (error) {
+        if (error instanceof TemplateDownloadError && options?.allowOfflineFallback && resolvedTemplate !== OFFLINE_FALLBACK_TEMPLATE && BUNDLED_TEMPLATES.includes(OFFLINE_FALLBACK_TEMPLATE)) {
+            await cleanupFailedImport(projectPath, ownsProjectDir, preExistingEntries);
+            await promises_namespaceObject.mkdir(projectPath, {
+                recursive: true
+            });
+            const fallback = await copyBundledTemplate(OFFLINE_FALLBACK_TEMPLATE, projectPath, logger, ownerGitignore);
+            if (fallback) {
+                logger.log(templateOfflineFallback(resolvedTemplateName, OFFLINE_FALLBACK_TEMPLATE, error));
+                return fallback;
+            }
+        }
         if (error instanceof TemplateNotFoundError) logger.error(templateNotFoundInCatalog(templateName, error.cause));
         else if (error instanceof TemplateDownloadError) logger.error(templateDownloadFailed(templateName, error));
         else logger.error(installingFromTemplateError(templateName, error));
@@ -887,8 +1049,22 @@ async function runGit(args, projectPath) {
         });
     });
 }
+async function hasCommittedHistory(projectPath) {
+    const inside = await runGit([
+        'rev-parse',
+        '--is-inside-work-tree'
+    ], projectPath);
+    if (!inside.ok) return false;
+    const head = await runGit([
+        'rev-parse',
+        '--verify',
+        'HEAD'
+    ], projectPath);
+    return head.ok;
+}
 async function initializeGitRepository(projectPath, projectName, templateName, logger) {
     if (isDebug()) logger.log(initializingGitForRepository(projectName));
+    if (await hasCommittedHistory(projectPath)) return void logger.log(existingRepositoryKept(projectName));
     const init = await runGit([
         'init',
         '--quiet'
@@ -1187,11 +1363,11 @@ async function hasDependenciesToInstall(projectPath) {
     const devDepsCount = Object.keys(packageJson?.devDependencies || {}).length;
     return depsCount + devDepsCount > 0;
 }
-async function installDependencies(projectPath, projectName, logger) {
+async function installDependencies(projectPath, projectName, logger, packageManager) {
     const nodeModulesPath = external_node_path_namespaceObject.join(projectPath, 'node_modules');
     const shouldInstall = await hasDependenciesToInstall(projectPath);
     if (!shouldInstall) return;
-    const command = isDenoRuntime() ? 'deno' : await getInstallCommand();
+    const command = packageManager ?? (isDenoRuntime() ? 'deno' : await getInstallCommand());
     const dependenciesArgs = 'deno' === command ? [
         'install'
     ] : getInstallArgs(command);
@@ -1515,7 +1691,8 @@ function resolveExtensionDevDependencyVersion(cliVersion) {
     if (!resolved) return 'latest';
     return resolved.includes('-') ? resolved : `^${resolved}`;
 }
-async function overridePackageJson(projectPath, { template = "javascript", cliVersion }, logger) {
+async function overridePackageJson(projectPath, options, logger) {
+    const { template = "javascript", cliVersion } = options;
     const extensionBinary = await resolveExtensionBinary();
     const candidatePath = external_node_path_namespaceObject.join(projectPath, 'package.json');
     let packageJson = {};
@@ -1537,7 +1714,8 @@ async function overridePackageJson(projectPath, { template = "javascript", cliVe
         ...packageJson.devDependencies || {},
         extension: 'development' === process.env.EXTENSION_ENV ? '*' : resolveExtensionDevDependencyVersion(cliVersion)
     };
-    const packageManagerSpec = packageJson.packageManager || (0, external_prefers_yarn_namespaceObject.getPackageManagerSpec)();
+    const packageManager = options.packageManager ?? resolveProjectPackageManager(projectPath);
+    const packageManagerSpec = resolvePackageManagerSpec(projectPath, packageManager);
     const declaredDeps = {
         ...packageJson.dependencies || {},
         ...packageJson.devDependencies || {}
@@ -1545,7 +1723,7 @@ async function overridePackageJson(projectPath, { template = "javascript", cliVe
     const usesMlNativeDeps = ML_DEP_TRIGGERS.some((dep)=>declaredDeps[dep]);
     const nativeBuildDeps = usesMlNativeDeps ? ML_NATIVE_BUILD_DEPENDENCIES : [];
     const existingPnpm = packageJson.pnpm && 'object' == typeof packageJson.pnpm ? packageJson.pnpm : {};
-    const installsWithPnpm = String(packageManagerSpec || '').startsWith('pnpm@') || 'pnpm' === resolveScaffoldPackageManager();
+    const installsWithPnpm = 'pnpm' === packageManager;
     const ignoredBuilt = uniq([
         ...existingPnpm.ignoredBuiltDependencies || [],
         ...installsWithPnpm ? BUILD_NOOP_DEPENDENCIES : []
@@ -1700,7 +1878,7 @@ const globalMisc = [
 ];
 const localSessionState = [
     '',
-    '# extension.js local session state',
+    '# Extension.js local session state',
     '.extension-js'
 ];
 const envFiles = [
@@ -1825,6 +2003,14 @@ async function write_readme_file_pathExists(target) {
         return false;
     }
 }
+function platformDocsUrl() {
+    return String(process.env.EXTENSION_DEV_DOCS_URL || '').trim().replace(/\/+$/, '');
+}
+function shipItSection() {
+    const docs = platformDocsUrl();
+    if (!docs) return '';
+    return `\n## Ship it\n\nBuilding and running your extension is local and free. When you are ready to share a build or submit it to the stores, see the [publish overview](${docs}/publish/overview?utm_source=create-readme).\n`;
+}
 async function writeReadmeFile(projectPath, projectName, logger) {
     const installCommand = await getInstallCommand();
     const deno = isDenoRuntime();
@@ -1838,7 +2024,7 @@ async function writeReadmeFile(projectPath, projectName, logger) {
     const screenshotHref = hasPublicScreenshot ? './public/screenshot.png' : hasRootScreenshot ? './screenshot.png' : null;
     const screenshotEmbed = screenshotHref ? `\n![screenshot](${screenshotHref})\n` : '';
     const blockquote = description ? `> ${description}\n\n` : '';
-    const readme = `<a href="https://extension.js.org" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Powered%20by%20%7C%20Extension.js-0971fe" alt="Powered by Extension.js" align="right" /></a>\n\n# ${projectName}\n\n` + blockquote + `${screenshotEmbed}` + `## Commands\n` + `\n` + `### dev\n` + `\n` + "Run the extension in development mode. Target a browser with `--browser`:\n" + `\n` + "```bash\n" + `${runPrefix} dev\n` + `${runPrefix} dev${argSeparator} --browser=firefox\n` + `${runPrefix} dev${argSeparator} --browser=edge\n` + "```\n" + `\n` + `### build\n` + `\n` + `Build for production. Convenience scripts target each browser:\n` + `\n` + "```bash\n" + `${runPrefix} build           # Chromium (default)\n` + `${runPrefix} build:firefox\n` + `${runPrefix} build:edge\n` + "```\n" + `\n` + `### preview\n` + `\n` + `Preview the production build in the browser:\n` + `\n` + "```bash\n" + `${runPrefix} preview\n` + "```\n" + `\n` + `## Learn more\n` + `\n` + `[Extension.js docs](https://extension.js.org).\n` + `\n` + `## Ship it\n` + `\n` + "Building and running your extension is local and free. When you are ready to share a build or submit it to the stores, [extension.dev](https://docs.extension.dev/publish/overview?utm_source=create-readme) " + `does that side and sponsors Extension.js.\n`;
+    const readme = `<a href="https://extension.js.org" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/Powered%20by%20%7C%20Extension.js-0971fe" alt="Powered by Extension.js" align="right" /></a>\n\n# ${projectName}\n\n` + blockquote + `${screenshotEmbed}` + `## Commands\n` + `\n` + `### dev\n` + `\n` + "Run the extension in development mode. Target a browser with `--browser`:\n" + `\n` + "```bash\n" + `${runPrefix} dev\n` + `${runPrefix} dev${argSeparator} --browser=firefox\n` + `${runPrefix} dev${argSeparator} --browser=edge\n` + "```\n" + `\n` + `### build\n` + `\n` + `Build for production. Convenience scripts target each browser:\n` + `\n` + "```bash\n" + `${runPrefix} build           # Chromium (default)\n` + `${runPrefix} build:firefox\n` + `${runPrefix} build:edge\n` + "```\n" + `\n` + `### preview\n` + `\n` + `Preview the production build in the browser:\n` + `\n` + "```bash\n" + `${runPrefix} preview\n` + "```\n" + `\n` + `## Learn more\n` + `\n` + `[Extension.js docs](https://extension.js.org).\n` + shipItSection();
     try {
         if (isDebug()) logger.log(writingReadmeMetaData());
         await promises_namespaceObject.mkdir(projectPath, {
@@ -1911,14 +2097,16 @@ async function writeTemplateProvenance(projectPath, provenance, logger) {
         logger.error(writingTemplateProvenanceError(error));
     }
 }
-async function extensionCreate(projectNameInput, { cliVersion, template = "javascript", install = false, logger = console }) {
+async function extensionCreate(projectNameInput, { cliVersion, template, install = false, logger = console }) {
     if (!projectNameInput) throw new Error(noProjectName());
+    const templateWasOmitted = null == template || '' === String(template).trim();
+    const effectiveTemplate = templateWasOmitted ? DEFAULT_TEMPLATE_NAME : String(template);
     if (projectNameInput.startsWith('http')) throw new Error(noUrlAllowed());
     const projectPath = external_node_path_namespaceObject.isAbsolute(projectNameInput) ? projectNameInput : external_node_path_namespaceObject.join(process.cwd(), projectNameInput);
     const projectName = external_node_path_namespaceObject.basename(projectPath);
     const updateSuffix = process.env.EXTENSION_CLI_UPDATE_SUFFIX || '';
     if (updateSuffix) delete process.env.EXTENSION_CLI_UPDATE_SUFFIX;
-    const requestedTemplate = String(template);
+    const requestedTemplate = effectiveTemplate;
     logger.log(' ');
     logger.log(card({
         version: cliVersion || process.env.EXTENSION_CLI_VERSION,
@@ -1941,28 +2129,32 @@ async function extensionCreate(projectNameInput, { cliVersion, template = "javas
     logger.log(' ');
     process.env.EXTENSION_CLI_BANNER_PRINTED = 'true';
     const createResult = await createDirectory(projectPath, projectName, logger);
-    const templateProvenance = await importExternalTemplate(projectPath, projectName, template, logger, {
-        ownsProjectDir: createResult?.directoryCreated ?? false
+    const templateProvenance = await importExternalTemplate(projectPath, projectName, effectiveTemplate, logger, {
+        ownsProjectDir: createResult?.directoryCreated ?? false,
+        allowOfflineFallback: templateWasOmitted
     });
     if (templateProvenance?.template) logger.log(usingTemplate(templateProvenance.template, templateProvenance.source));
-    const isMonorepoTemplate = String(template).toLowerCase().includes('monorepo');
+    const scaffoldedTemplate = templateProvenance?.template ?? effectiveTemplate;
+    const packageManager = resolveProjectPackageManager(projectPath);
+    const isMonorepoTemplate = String(scaffoldedTemplate).toLowerCase().includes('monorepo');
     if (isDenoRuntime() && !isMonorepoTemplate) await writeDenoJsonc(projectPath, {
-        template,
+        template: scaffoldedTemplate,
         cliVersion,
         primary: true
     }, logger);
     else {
         await overridePackageJson(projectPath, {
-            template,
-            cliVersion
+            template: scaffoldedTemplate,
+            cliVersion,
+            packageManager
         }, logger);
         await writeDenoJsonc(projectPath, {
-            template
+            template: scaffoldedTemplate
         }, logger);
     }
     await writeTemplateProvenance(projectPath, templateProvenance, logger);
     if (install) {
-        await installDependencies(projectPath, projectName, logger);
+        await installDependencies(projectPath, projectName, logger, packageManager);
         await installInternalDependencies(projectPath, logger);
     }
     await writeReadmeFile(projectPath, projectName, logger);
@@ -1970,16 +2162,16 @@ async function extensionCreate(projectNameInput, { cliVersion, template = "javas
     await writeStoreMetadata(projectPath, projectName, templateManifestName, logger);
     await writeGitignore(projectPath, logger);
     await setupBuiltInTests(projectPath, logger);
-    if (isTypeScriptTemplate(template)) await generateExtensionTypes(projectPath, projectName, logger);
+    if (isTypeScriptTemplate(scaffoldedTemplate)) await generateExtensionTypes(projectPath, projectName, logger);
     await initializeGitRepository(projectPath, projectName, templateProvenance?.template, logger);
-    const readyMessage = await scaffoldReady(projectPath, projectName, Boolean(install));
+    const readyMessage = await scaffoldReady(projectPath, projectName, Boolean(install), packageManager);
     logger.log(readyMessage);
     return {
         projectPath,
         projectName,
-        template: templateProvenance?.template ?? template,
+        template: templateProvenance?.template ?? scaffoldedTemplate,
         depsInstalled: install,
-        packageManager: resolveScaffoldPackageManager(),
+        packageManager,
         templateProvenance
     };
 }

package/dist/steps/import-external-template.d.ts

@@ -1,5 +1,7 @@
 export declare const DEFAULT_TEMPLATES_REF = "cb6a25377bd9516a1e55447a2010537019851ab2";
 export declare const BUNDLED_TEMPLATES: readonly string[];
+export declare const DEFAULT_TEMPLATE_NAME = "typescript";
+export declare const OFFLINE_FALLBACK_TEMPLATE = "javascript";
 export declare function resolveCatalogUrls(ref: string, overrideUrl?: string): string[];
 export interface TemplateProvenance {
     template: string;
@@ -23,6 +25,7 @@ export declare const TEMPLATE_LOCKFILE_NAMES: string[];
 export declare function removeStaleTemplateLockfiles(projectPath: string): Promise<string[]>;
 export interface ImportExternalTemplateOptions {
     ownsProjectDir?: boolean;
+    allowOfflineFallback?: boolean;
 }
 export declare function cleanupFailedImport(projectPath: string, ownsProjectDir: boolean, preExistingEntries: string[]): Promise<void>;
 export declare function importExternalTemplate(projectPath: string, projectName: string, template: string, logger: {

package/dist/steps/install-dependencies.d.ts

@@ -1,4 +1,5 @@
+import { type ScaffoldPackageManager } from '../lib/package-manager';
 export declare function installDependencies(projectPath: string, projectName: string, logger: {
     log(...args: unknown[]): void;
     error(...args: unknown[]): void;
-}): Promise<void>;
+}, packageManager?: ScaffoldPackageManager): Promise<void>;

package/dist/steps/write-package-json.d.ts

@@ -1,12 +1,15 @@
+import { type ScaffoldPackageManager } from '../lib/package-manager';
 export declare function resolveExtensionBinary(): Promise<string>;
 export declare function getTemplateAwareScripts(template: string, extensionBinary: string): Record<string, string>;
 interface OverridePackageJsonOptions {
     /** Defaults to `javascript` when omitted (same as `extensionCreate`). */
     template?: string;
     cliVersion?: string;
+    /** The one manager the project uses; resolved from the scaffold when omitted. */
+    packageManager?: ScaffoldPackageManager;
 }
 export declare function resolveExtensionDevDependencyVersion(cliVersion?: string): string;
-export declare function overridePackageJson(projectPath: string, { template, cliVersion }: OverridePackageJsonOptions, logger: {
+export declare function overridePackageJson(projectPath: string, options: OverridePackageJsonOptions, logger: {
     log(...args: unknown[]): void;
     error(...args: unknown[]): void;
 }): Promise<void>;

package/dist/test-template-javascript/.extension-create.json

@@ -1,5 +1,6 @@
 {
-  "createdWith": "extension-create@4.1.10",
-  "template": "javascript",
-  "source": "bundled"
+  "createdWith": "extension-create@4.1.12",
+  "template": "typescript",
+  "source": "https://codeload.github.com/extension-js/examples/zip/cb6a25377bd9516a1e55447a2010537019851ab2",
+  "ref": "cb6a25377bd9516a1e55447a2010537019851ab2"
 }

package/dist/test-template-javascript/README.md

@@ -37,7 +37,3 @@ pnpm run preview
 ## Learn more
 
 [Extension.js docs](https://extension.js.org).
-
-## Ship it
-
-Building and running your extension is local and free. When you are ready to share a build or submit it to the stores, [extension.dev](https://docs.extension.dev/publish/overview?utm_source=create-readme) does that side and sponsors Extension.js.

package/dist/test-template-javascript/STORE.md

@@ -9,7 +9,7 @@ Packaging your extension is local and free. Submitting the result to a
 store is what [extension.dev](https://docs.extension.dev/publish/overview?utm_source=store-md)
 does, and it sponsors Extension.js.
 
-Last updated: 2026-08-31
+Last updated: 2026-09-05
 
 ## Listing
 
@@ -65,5 +65,5 @@ notes in most cases.
 
 ## Version history
 
-- 1.0.0 (unreleased): initial version from the javascript template.
+- 1.0.0 (unreleased): initial version from the typescript template.
   Not yet submitted to any store.

package/dist/test-template-javascript/extension.config.js

@@ -2,18 +2,14 @@
 // Extension.js uses a fresh profile on every run.
 // Prefer that default? Remove the profile config below.
 const profile = (name) => `./dist/extension-profile-${name}`
-const ciFlags = process.env.CI ? ['--no-sandbox', '--disable-gpu'] : []
 
 export default {
   browser: {
-    chrome: {profile: profile('chrome'), browserFlags: ciFlags},
-    chromium: {profile: profile('chromium'), browserFlags: ciFlags},
-    edge: {profile: profile('edge'), browserFlags: ciFlags},
+    chrome: {profile: profile('chrome')},
+    chromium: {profile: profile('chromium')},
+    edge: {profile: profile('edge')},
     firefox: {profile: profile('firefox')},
-    'chromium-based': {
-      profile: profile('chromium-based'),
-      browserFlags: ciFlags
-    },
+    'chromium-based': {profile: profile('chromium-based')},
     'gecko-based': {profile: profile('gecko-based')}
   }
 }

package/dist/test-template-javascript/package.json

@@ -5,6 +5,10 @@
   "version": "1.0.0",
   "license": "MIT",
   "type": "module",
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "extension": "^4.1.12"
+  },
   "scripts": {
     "dev": "extension dev",
     "start": "extension start",
@@ -15,9 +19,6 @@
     "build:edge": "extension build --browser edge"
   },
   "dependencies": {},
-  "devDependencies": {
-    "extension": "^4.1.10"
-  },
   "packageManager": "pnpm@10.28.0",
   "pnpm": {
     "ignoredBuiltDependencies": [

package/dist/test-template-javascript/src/{background.js → background.ts}

@@ -11,7 +11,7 @@ if (isFirefoxLike) {
     browser.sidebarAction.open()
   })
 
-  browser.runtime.onMessage.addListener((message) => {
+  browser.runtime.onMessage.addListener((message: any) => {
     if (!message || message.type !== 'openSidebar') return
 
     browser.sidebarAction.open()
@@ -19,7 +19,7 @@ if (isFirefoxLike) {
 }
 
 if (!isFirefoxLike) {
-  // setPanelBehavior only affects FUTURE action clicks, registering it
+  // setPanelBehavior only affects FUTURE action clicks — registering it
   // inside onClicked would swallow the first toolbar click.
   chrome.sidePanel.setPanelBehavior({openPanelOnActionClick: true})
 }
@@ -32,7 +32,7 @@ chrome.runtime.onMessage.addListener((message) => {
   if (!chrome.sidePanel.open) return
 
   chrome.tabs.query({active: true, currentWindow: true}, (tabs) => {
-    const activeTabId = tabs?.[0]?.id
+    const activeTabId = tabs && tabs[0] && tabs[0].id
     if (!activeTabId) return
 
     try {

package/dist/test-template-javascript/src/content/{ContentApp.js → ContentApp.ts}

@@ -1,6 +1,6 @@
 import logo from '../images/icon.png'
 
-export default function createContentApp() {
+export default function createContentApp(): HTMLDivElement {
   const container = document.createElement('div')
   container.className = 'content_script'
 
@@ -9,22 +9,17 @@ export default function createContentApp() {
   pill.className = 'content_pill'
   pill.setAttribute('aria-label', 'Open sidebar')
   pill.addEventListener('click', () => {
-    try {
-      if (
-        import.meta.env.EXTENSION_PUBLIC_BROWSER === 'firefox' ||
-        import.meta.env.EXTENSION_PUBLIC_BROWSER === 'gecko-based'
-      ) {
-        browser.runtime.sendMessage({type: 'openSidebar'})
-      } else {
-        chrome.runtime.sendMessage({type: 'openSidebar'})
-      }
-    } catch (error) {
-      console.error(error)
+    if (import.meta.env.EXTENSION_PUBLIC_BROWSER === 'firefox') {
+      browser.runtime.sendMessage({type: 'openSidebar'})
+    } else {
+      chrome.runtime.sendMessage({type: 'openSidebar'})
     }
   })
 
   const img = document.createElement('img')
   img.className = 'content_pill_logo'
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
   img.src = logo
   img.alt = ''
   img.setAttribute('aria-hidden', 'true')

package/dist/test-template-javascript/src/content/{scripts.js → scripts.ts}

@@ -1,4 +1,4 @@
-import createContentApp from './ContentApp.js'
+import createContentApp from './ContentApp'
 import './styles.css'
 
 console.log('[From the page context] Hello from content_scripts!')

package/dist/test-template-javascript/src/content/types.d.ts

@@ -0,0 +1,15 @@
+declare global {
+  interface ImportMeta {
+    webpackHot?: {
+      accept: (module?: string, callback?: () => void) => void
+      dispose: (callback: () => void) => void
+    }
+  }
+}
+
+declare module '*.svg' {
+  const content: string
+  export default content
+}
+
+export {}

package/dist/test-template-javascript/src/manifest.json

@@ -53,9 +53,9 @@
     "sidePanel"
   ],
   "background": {
-    "chromium:service_worker": "background.js",
+    "chromium:service_worker": "background.ts",
     "firefox:scripts": [
-      "background.js"
+      "background.ts"
     ]
   },
   "content_scripts": [
@@ -64,7 +64,7 @@
         "<all_urls>"
       ],
       "js": [
-        "content/scripts.js"
+        "content/scripts.ts"
       ]
     }
   ]

package/dist/test-template-javascript/src/sidebar/{SidebarApp.js → SidebarApp.ts}

@@ -1,5 +1,4 @@
-import './styles.css'
-import javascriptLogo from '../images/icon.png'
+import typescriptLogo from '../images/icon.png'
 
 function SidebarApp() {
   const root = document.getElementById('root')
@@ -9,8 +8,8 @@ function SidebarApp() {
     <div class="sidebar_app">
       <img
         class="sidebar_logo"
-        src="${javascriptLogo}"
-        alt="The JavaScript logo"
+        src="${typescriptLogo}"
+        alt="The TypeScript logo"
       />
       <h1 class="sidebar_title">Sidebar Panel</h1>
       <p class="sidebar_description">

package/dist/test-template-javascript/src/sidebar/index.html

@@ -3,11 +3,11 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>JavaScript Sidebar</title>
+    <title>TypeScript Sidebar</title>
   </head>
   <body>
     <noscript>You need to enable JavaScript to run this extension.</noscript>
     <div id="root"></div>
   </body>
-  <script src="./scripts.js"></script>
+  <script src="./scripts.ts"></script>
 </html> 

package/dist/test-template-javascript/src/sidebar/{scripts.js → scripts.ts}

@@ -1,4 +1,4 @@
-import './SidebarApp.js'
+import './SidebarApp'
 import './styles.css'
 
 console.log('[From the sidebar page context] Hello regular page!')

package/dist/test-template-javascript/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "target": "esnext",
+    "verbatimModuleSyntax": false,
+    "useDefineForClassFields": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["./", "extension-env.d.ts", "browser-global.d.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -25,7 +25,7 @@
     "templates"
   ],
   "name": "extension-create",
-  "version": "4.1.11",
+  "version": "4.1.13",
   "description": "The standalone extension creation engine for Extension.js",
   "author": {
     "name": "Cezar Augusto",