SDK de JavaScript: gestor de archivos de la app

El gestor de archivos está en api.apps.files. Todos los métodos reciben primero el id de la aplicación y después una ruta dentro de la aplicación. Las rutas tienen como máximo 256 caracteres. Los ejemplos usan el cliente api de Crear el cliente. appId es el id de una de tus aplicaciones: api.account.me() las lista.

Listar un directorio

files.list(appId, path?) lista un directorio (la raíz de la aplicación cuando se omite path).

for (const entry of await api.apps.files.list(appId, "/src")) {
    console.log(entry.type, entry.name, entry.size, entry.lastModified);
}

Campo	Tipo	Descripción
`name`	`string`	Nombre de la entrada
`type`	`"file" \| "directory"`	Tipo de entrada
`size`	`number?`	Tamaño en bytes. Ausente en algunas entradas de directorio
`lastModified`	`number \| null?`	Ms Unix (puede incluir decimales); `null` cuando no se puede leer

Un directorio que no existe da 404 FILE_NOT_FOUND. Una ruta que el gestor de archivos no expone da 403 BLOCKED_PATH.

Leer un archivo

files.read(appId, path) devuelve los bytes del archivo como un Uint8Array. Los archivos están limitados a 10 MB: uno más grande da 413 FILE_TOO_LARGE.

const bytes = await api.apps.files.read(appId, "/config.json");
const text = new TextDecoder().decode(bytes);

console.log(JSON.parse(text));

Escribir un archivo

files.write(appId, path, content, { signal }) crea o sobrescribe un archivo.

Un string se envía como texto plano.
Un Uint8Array se envía en base64, así que cualquier contenido binario se conserva intacto.
Un contenido vacío ("" o bytes vacíos) crea un archivo vacío.

// Text
await api.apps.files.write(appId, "/config.json", JSON.stringify({ debug: false }));

// Binary
const image = new Uint8Array(await (await fetch(imageUrl)).arrayBuffer());
await api.apps.files.write(appId, "/assets/logo.png", image);

Un contenido de más de 10 MB falla localmente con FILE_TOO_LARGE (estado 0) antes de enviar nada. Un contenido de más de 1 MiB se envía sin timeout, como una subida: pasa { signal } para cancelarlo. Para archivos más grandes, usa apps.commit().

Escribir no reinicia la aplicación. Llama a apps.restart() para aplicar el cambio.

Mover o renombrar un archivo

await api.apps.files.move(appId, "/config.json", "/config.old.json");

Eliminar un archivo

await api.apps.files.delete(appId, "/config.old.json");

Errores

Estado	Código	Cuándo
0	`FILE_TOO_LARGE`	Contenido de `write` de más de 10 MB (se comprueba localmente)
400	`INVALID_PATH`	La ruta no supera la validación (traversal, caracteres no válidos, demasiado larga), o `move` a la misma ruta
400	`DELETE_FAILED`, `RENAME_FAILED`	El clúster no pudo eliminar o renombrar el archivo
403	`BLOCKED_PATH`	El gestor de archivos no expone la ruta
403	`PERMISSION_DENIED`	Tu rol en el workspace no puede tocar un archivo restringido (como `.env`)
404	`FILE_NOT_FOUND`	El archivo o directorio no existe
413	`FILE_TOO_LARGE`	`read` de un archivo de más de 10 MB
429	`KEEP_CALM`	Más de 10 escrituras en 5 segundos

Consulta Errores para ver los códigos que puede devolver cualquier llamada.

Próximos pasos

Variables de entorno

Lee y cambia las variables de una aplicación.

Referencia de la API del gestor de archivos

Los endpoints REST detrás de estos métodos.

Gestionar archivos desde la CLI

Las mismas acciones desde la terminal.

CLI

VS Code

SDKs

SDK de JavaScript: gestor de archivos de la app

Listar un directorio

Leer un archivo

Escribir un archivo

Mover o renombrar un archivo

Eliminar un archivo

Errores

Próximos pasos

Variables de entorno

Referencia de la API del gestor de archivos

Gestionar archivos desde la CLI

​Listar un directorio

​Leer un archivo

​Escribir un archivo

​Mover o renombrar un archivo

​Eliminar un archivo

​Errores

​Próximos pasos

Variables de entorno

Referencia de la API del gestor de archivos

Gestionar archivos desde la CLI

Listar un directorio

Leer un archivo

Escribir un archivo

Mover o renombrar un archivo

Eliminar un archivo

Errores

Próximos pasos