{"record":{"id":"54c431b432e36153","repo":"sinelaw/fresh","slug":"pkg-package-packagename-requires-plugin-api-version-manifest","errorCode":null,"errorMessage":"[pkg] Package '${packageName}' requires plugin API version ${manifest.fresh.min_api_version}, but this editor only supports version ${currentApi}. Some features may not work. Update Fresh to get the latest plugin API.","messagePattern":"\\[pkg\\] Package '(.+?)' requires plugin API version (.+?), but this editor only supports version (.+?)\\. Some features may not work\\. Update Fresh to get the latest plugin API\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/fresh-editor/plugins/pkg.ts","lineNumber":788,"sourceCode":"  if (!manifest.type) {\n    return {\n      valid: false,\n      error: \"Invalid package.json - missing 'type' field (should be 'plugin', 'theme', 'language', or 'bundle')\"\n    };\n  }\n\n  if (manifest.type !== \"plugin\" && manifest.type !== \"theme\" && manifest.type !== \"language\" && manifest.type !== \"bundle\") {\n    return {\n      valid: false,\n      error: `Invalid package.json - 'type' must be 'plugin', 'theme', 'language', or 'bundle', got '${manifest.type}'`\n    };\n  }\n\n  // Warn if package requires a newer plugin API version\n  if (manifest.fresh?.min_api_version) {\n    const currentApi = editor.apiVersion();\n    if (manifest.fresh.min_api_version > currentApi) {\n      editor.warn(\n        `[pkg] Package '${packageName}' requires plugin API version ${manifest.fresh.min_api_version}, ` +\n        `but this editor only supports version ${currentApi}. Some features may not work. ` +\n        `Update Fresh to get the latest plugin API.`\n      );\n    }\n  }\n\n  // For plugins, validate entry file exists\n  if (manifest.type === \"plugin\") {\n    const entryFile = manifest.fresh?.entry || manifest.fresh?.main || `${manifest.name}.ts`;\n    const entryPath = editor.pathJoin(packageDir, entryFile);\n\n    if (!fsLocal.fileExists(entryPath)) {\n      // Try .js as fallback\n      const jsEntryPath = entryPath.replace(/\\.ts$/, \".js\");\n      if (fsLocal.fileExists(jsEntryPath)) {\n        return { valid: true, manifest, entryPath: jsEntryPath };\n      }","sourceCodeStart":770,"sourceCodeEnd":806,"githubUrl":"https://github.com/sinelaw/fresh/blob/67894ca5463dbd7a89bb31add4627c27d6b79d83/crates/fresh-editor/plugins/pkg.ts#L770-L806","documentation":"In pkg.ts validatePackage(), if a package manifest declares fresh.min_api_version greater than the editor's current plugin API version (editor.apiVersion()), a compatibility warning is emitted. The package is still accepted — validation does not fail — but some features may misbehave until the editor is updated.","triggerScenarios":"Installing or validating any package whose manifest contains fresh.min_api_version newer than the running editor supports; validatePackage is invoked from both the local and registry install paths.","commonSituations":"Package published against a newer editor release while the user runs an older editor; skipping editor updates for a long time then installing recently published packages; pinning an older editor version in CI.","solutions":["Update the Fresh editor to a version whose plugin API is at least manifest.fresh.min_api_version.","If updating is not possible, downgrade the package to a version built for your editor's API.","Contact the package maintainer to lower min_api_version if the package does not actually need newer APIs.","Accept the warning only if you don't rely on the newer plugin API features."],"exampleFix":"// manifest\n[fresh]\nmin_api_version = 5\n// editor.apiVersion() = 4 -> update editor, or pin package version built for API 4","handlingStrategy":"validation","validationCode":"const manifest = parseToml(fs.readFileSync(pkgManifest, 'utf8'));\nconst need = manifest?.fresh?.min_api_version ?? 0;\nif (need > editor.apiVersion()) console.warn(`update editor: package needs API ${need}, have ${editor.apiVersion()}`);","typeGuard":"function apiCompatible(manifest, currentApi) { return !(manifest?.fresh?.min_api_version > currentApi); }","tryCatchPattern":"const v = validatePackage(dir, name);\nif (v.valid && !apiCompatible(v.manifest, editor.apiVersion())) {\n  if (!confirm('package may misbehave; install anyway?')) return;\n}","preventionTips":["Keep the editor updated before installing recently published packages.","Check a package's declared min_api_version against editor.apiVersion() in automated setup scripts.","Pin package versions compatible with your editor when running older editors (e.g. CI).","Subscribe to editor release notes for plugin API bumps."],"tags":["package-management","version-compatibility","plugin-api"],"backgroundTag":"incompatible-source-type","analyzedSha":"67894ca5463dbd7a89bb31add4627c27d6b79d83","analyzedAt":"2026-09-13T15:04:03.701Z","contentChangedAt":"2026-09-13T15:04:03.701Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}