file() — astro Function Reference

Architecture documentation for the file() function in file.ts from the astro codebase.

Function typescript ContentCollections DataLoaders

Entity Profile

ContentCollections→ DataLoaders→ file() — astro Function Reference

Dependency Diagram

graph TD
  a5602415_268d_eaab_0e00_aee878bd0a03["file()"]
  7fd49d85_29da_fb8a_f2fc_3479c947eee8["file.ts"]
  a5602415_268d_eaab_0e00_aee878bd0a03 -->|defined in| 7fd49d85_29da_fb8a_f2fc_3479c947eee8
  style a5602415_268d_eaab_0e00_aee878bd0a03 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/astro/src/content/loaders/file.ts lines 25–129

export function file(fileName: string, options?: FileOptions): Loader {
	if (fileName.includes('*')) {
		throw new AstroError(FileGlobNotSupported);
	}

	let parse: ((text: string) => any) | null = null;

	const ext = fileName.split('.').at(-1);
	if (ext === 'json') {
		parse = JSON.parse;
	} else if (ext === 'yml' || ext === 'yaml') {
		parse = (text) =>
			yaml.load(text, {
				filename: fileName,
			});
	} else if (ext === 'toml') {
		parse = toml.parse;
	}
	if (options?.parser) parse = options.parser;

	if (parse === null) {
		throw new AstroError({
			...FileParserNotFound,
			message: FileParserNotFound.message(fileName),
		});
	}

	async function syncData(filePath: string, { logger, parseData, store, config }: LoaderContext) {
		let data: Array<Record<string, unknown>> | Record<string, Record<string, unknown>>;

		try {
			const contents = await fs.readFile(filePath, 'utf-8');
			data = await parse!(contents);
		} catch (error: any) {
			logger.error(`Error reading data from ${fileName}`);
			logger.debug(error.message);
			return;
		}

		const normalizedFilePath = posixRelative(fileURLToPath(config.root), filePath);

		if (Array.isArray(data)) {
			if (data.length === 0) {
				logger.warn(`No items found in ${fileName}`);
			}
			logger.debug(`Found ${data.length} item array in ${fileName}`);
			store.clear();
			const idList = new Set();
			for (const rawItem of data) {
				const id = (rawItem.id ?? rawItem.slug)?.toString();
				if (!id) {
					logger.error(`Item in ${fileName} is missing an id or slug field.`);
					continue;
				}
				if (idList.has(id)) {
					logger.warn(
						`Duplicate id "${id}" found in ${fileName}. Later items with the same id will overwrite earlier ones.`,
					);
				}
				idList.add(id);
				const parsedData = await parseData({ id, data: rawItem, filePath });
				store.set({ id, data: parsedData, filePath: normalizedFilePath });
			}
		} else if (typeof data === 'object') {
			const entries = Object.entries<Record<string, unknown>>(data);
			logger.debug(`Found object with ${entries.length} entries in ${fileName}`);
			store.clear();
			for (const [id, rawItem] of entries) {
				if (id === '$schema' && typeof rawItem === 'string') {
					// Ignore JSON schema field.
					continue;
				}
				const parsedData = await parseData({ id, data: rawItem, filePath });
				store.set({ id, data: parsedData, filePath: normalizedFilePath });
			}
		} else {
			logger.error(`Invalid data in ${fileName}. Must be an array or object.`);
		}
	}

	return {