npm install sharp

No iOS/Android steps are required. This is a Node.js-only package.

Project setup

1. Drop source/ into your project root, e.g., ./astro-source/.

2. Alias the package so your code resolves astro from the local source instead of (or alongside) the published package. In tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "astro": ["./astro-source/src/index.ts"],
      "astro/components": ["./astro-source/components/index.ts"],
      "astro/assets": ["./astro-source/src/assets/index.ts"],
      "astro/assets/utils": ["./astro-source/src/assets/utils/index.ts"]
    },
    "moduleResolution": "bundler",
    "target": "ESNext",
    "module": "ESNext"
  }
}

3. Extend the Astro tsconfig preset in your project tsconfig.json:

{
  "extends": "./astro-source/tsconfigs/base.json"
}

4. Set required environment variables in .env or your host environment:

# Required if using Astro's env module features
ASTRO_KEY=your_secret

5. Wire Vite — if using Astro internals inside a plain Vite/Node project, import from src/ directly and ensure "type": "module" is in your package.json.

6. For production builds invoked outside the CLI, call the Astro programmatic API exported from src/core/index.ts (see Public API below).

Public API

getImage

import { getImage } from 'astro/assets';

async function getImage(
  options: { src: ImageMetadata | string; width?: number; height?: number; format?: string; quality?: number | string },
  serviceConfig?: Record<string, unknown>
): Promise<{ src: string; attributes: Record<string, unknown> }>

Use getImage to programmatically resolve and transform an image through the configured image service. Useful in API routes, content collection loaders, or when you need the final URL of an optimized image without using the <Image /> component.

isRemoteImage

import { isRemoteImage } from 'astro/assets/utils';

function isRemoteImage(src: string | ImageMetadata): src is string

Returns true when the source is a remote URL string rather than a local ESM-imported image object. Use this guard before calling remote-specific sizing utilities such as inferRemoteSize.

imageMetadata

import { imageMetadata } from 'astro/assets/utils';

function imageMetadata(
  buffer: Buffer,
  src?: string
): Promise<{ width: number; height: number; format: string; orientation?: number }>

Extracts width, height, and format metadata from a raw image buffer. Useful in build-time scripts or custom integrations that process image files before handing them to Astro's asset pipeline.

Code (component)

import { Code } from 'astro/components';
// Props: { code: string; lang?: string; theme?: string; wrap?: boolean }

A built-in syntax-highlighted code block component backed by Shiki. Use it in .astro files wherever you need to render code samples with zero client JavaScript.

isRemoteAllowed

import { isRemoteAllowed } from 'astro/assets/utils';

function isRemoteAllowed(src: string, patterns: RemotePattern[]): boolean

Checks whether a remote image URL matches the allowlist of RemotePattern objects defined in astro.config. Use this in custom image loaders or middleware before fetching remote assets.

Working examples

Scenario - Programmatic image optimization in a build script

You have a Node.js build script that needs to generate optimized image URLs for a static data file.

import { getImage } from 'astro/assets';
import { imageMetadata, isRemoteImage } from 'astro/assets/utils';
import { readFileSync } from 'node:fs';

const rawBuffer = readFileSync('./public/hero.png');
const meta = await imageMetadata(rawBuffer, 'hero.png');
console.log(`Original: ${meta.width}x${meta.height} (${meta.format})`);

const result = await getImage({ src: '/public/hero.png', width: 800, format: 'webp' });
console.log('Optimized URL:', result.src);

Scenario - Validating remote image sources against an allowlist

You run a middleware that must reject disallowed remote images before processing.

import { isRemoteAllowed, isRemoteImage } from 'astro/assets/utils';
import type { RemotePattern } from 'astro/assets/utils';

const allowedPatterns: RemotePattern[] = [
  { protocol: 'https', hostname: 'images.example.com' },
  { protocol: 'https', hostname: '**.cdn.net' },
];

function validateImageSrc(src: string | unknown): boolean {
  if (!isRemoteImage(src as string)) {
    // local ESM image — always allowed
    return true;
  }
  return isRemoteAllowed(src as string, allowedPatterns);
}

const ok = validateImageSrc('https://images.example.com/photo.jpg');
const blocked = validateImageSrc('https://evil.com/track.gif');
console.log(ok, blocked); // true, false

Scenario - Using built-in components in an Astro page

Render a syntax-highlighted code sample and a debug dump inside an .astro file.

---
import { Code, Debug } from 'astro/components';

const exampleCode = `const greeting = "Hello, Astro!";`;
const data = { version: 5, mode: 'production' };
---

<html>
  <body>
    <Code code={exampleCode} lang="ts" theme="github-dark" />
    <Debug {data} />
  </body>
</html>

Scenario - Probing remote image dimensions before rendering

Before inserting a remote image into a layout, infer its dimensions to avoid layout shift.

import { inferRemoteSize } from 'astro/assets/utils';
import { isRemoteImage } from 'astro/assets/utils';

const src = 'https://images.example.com/banner.jpg';

if (isRemoteImage(src)) {
  const { width, height } = await inferRemoteSize(src);
  console.log(`Remote image is ${width}x${height}`);
}

File walkthrough

• bin/astro.mjs - Thin CLI shim that bootstraps the Astro command dispatcher.
• components/index.ts - Exports Code and Debug built-in Astro components for use in .astro files.
• components/viewtransitions.css - Default CSS for the View Transitions API integration.
• performance/ - Standalone benchmark harness; not part of the runtime, used for CI perf tracking.
• src/actions/ - Server action definitions and runtime wiring for type-safe form/API mutations.
• src/assets/ - Image optimization pipeline: services, utils, font providers, metadata extraction.
• src/cli/ - CLI command implementations (dev, build, preview, check, sync).
• src/config/ - Config loading, validation (via Zod), and normalization logic.
• src/container/ - Programmatic rendering container API for rendering components in isolation.
• src/content/ - Content collections: loaders, querying, schema validation.
• src/core/ - Core build orchestration, routing, rendering pipeline, and public API surface.
• src/env/ - Typed environment variable system (astro:env).
• src/i18n/ - Internationalization utilities and routing helpers.
• src/integrations/ - Integration hook runner and lifecycle management.
• src/jsx/ - JSX transform and Astro-flavored JSX runtime.
• src/manifest/ - Route manifest generation for SSR and static builds.
• src/prefetch/ - Client-side prefetch logic for the <link rel="prefetch"> integration.
• src/runtime/ - Server and client runtime helpers used at request time.
• src/toolbar/ - Astro Dev Toolbar component system and server hooks.
• src/transitions/ - View Transitions API router and animation utilities.
• src/types/ - All public TypeScript types re-exported via src/index.ts.
• src/vite-plugin-*/ - Individual Vite plugins composing the Astro build pipeline.
• templates/ - HTML/Astro templates for error pages and dev server overlays.
• tsconfigs/ - Shareable TS config presets (base, strict, strictest).
• types/ - Ambient .d.ts files for non-TS consumers and global augmentations.

Common pitfalls and fixes

• ESM-only package: astro is pure ESM. Ensure "type": "module" in your package.json or use .mjs extensions; CommonJS require() will fail.
• moduleResolution must be bundler or node16+: Using "moduleResolution": "node" breaks Astro's exports-map subpath imports (astro/assets, astro/components). Fix by setting "moduleResolution": "bundler" in tsconfig.json.
• sharp not found for local image optimization: Astro tries to use sharp at build time. Install it explicitly with npm install sharp and ensure it is compiled for your Node version (npm rebuild sharp).
• unifont peer required for font providers: Calling adobe(), bunny(), or google() without unifont installed throws at runtime. Always install unifont when using src/assets/fonts/providers/.
• Path aliases must be duplicated in Vite config: tsconfig.json paths are TypeScript-only. If you also run Vite directly, mirror the aliases in vite.config.ts using resolve.alias.
• getImage requires an active image service: Calling getImage outside an Astro build context (no service configured) returns an unoptimized passthrough. Configure image.service in astro.config.mjs or call getConfiguredImageService() first to verify.

Vibe-coding prompt template

I have the Astro core framework source in `./astro-source/` and its integration
guide at `./astro-source/USAGE.md`. The upstream package is `astro` (withastro/astro,
packages/astro). My project is a Node.js/TypeScript application using Vite.

Please help me integrate this source step by step:

1. Read USAGE.md and the file excerpts from `./astro-source/src/assets/index.ts`,
   `./astro-source/src/assets/utils/index.ts`, and
   `./astro-source/components/index.ts` to understand the real exported API.

2. Update my `tsconfig.json` to add path aliases for `astro`, `astro/assets`,
   `astro/assets/utils`, and `astro/components` pointing into `./astro-source/`.

3. In my existing image processing module, replace any manual image sizing logic
   with `imageMetadata` and `inferRemoteSize` from `astro/assets/utils`, and use
   `isRemoteImage` to branch between local and remote sources.

4. Add `getImage` from `astro/assets` to my build script to generate optimized
   image URLs with format `webp` and width 1200.

5. Ensure `sharp` and `unifont` are installed if I use local image optimization
   or font providers.

6. Show me a working example `.astro` page that uses the `Code` and `Debug`
   built-in components imported from `astro/components`.

Do not invent any exports. Only use symbols documented in USAGE.md.

License and credit

Astro is released under the MIT License. See source/LICENSE if present, or refer to the official repository for the full license text. Upstream package: astro by the Astro core team.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.