ApostropheCMS

Appearance

Edit this page on GitHub or open an issue

@apostrophecms/file ​

Alias: apos.file

Extends: @apostrophecms/piece-type ℹ️

This module establishes a library of uploaded files in Apostrophe, which may be of any type acceptable to the @apostrophecms/attachment module. Together with @apostrophecms/file-widget, it provides a way to add downloadable PDFs and other documents to a website and to manage a library of them for reuse.

Files are autopublished, meaning saved changes are immediately live. This eliminates the need for editors to manage draft and published states for uploaded files while still preserving localization support.

Options ​

PropertyTypeDescription
insertViaUploadBooleanDefaults to true. Enables uploading files directly from the manager modal.
prettyUrlsBooleanDefaults to false. Enables human-readable file URLs.
prettyUrlDirStringDefaults to '/files'. The URL path prefix for pretty URLs.
slugPrefixStringDefaults to 'file-'. Prefix applied to file slugs.

insertViaUpload ​

Defaults to true. When enabled, a file upload button is available in the file manager modal, allowing users to upload new files directly. Set to false to disable this feature.

Example ​

javascript
module.exports = {
  options: {
    insertViaUpload: false
  }
};
modules/@apostrophecms/file/index.js

prettyUrls ​

Defaults to false. When set to true, files are served at human-readable URLs based on their slug, rather than the default uploadfs URL. For example, a file with the slug file-annual-report and a .pdf extension would be available at /files/annual-report.pdf (with the slugPrefix stripped from the URL).

The pretty URL route streams the file content from the underlying uploadfs storage, so the file is still stored in the same location. There is a slight performance penalty for using this option, as each request is proxied through the Node.js process rather than being served directly by the storage backend or CDN.

If you wish to use this feature with an Astro project, you'll need to add /files to proxyRoutes in your astro.config.mjs file. This feature is not yet compatible with our new static build feature.

Example ​

javascript
module.exports = {
  options: {
    prettyUrls: true
  }
};
modules/@apostrophecms/file/index.js

prettyUrlDir ​

Defaults to '/files'. Sets the URL path prefix used when prettyUrls is enabled. Only takes effect when prettyUrls is true.

Example ​

javascript
module.exports = {
  options: {
    prettyUrls: true,
    prettyUrlDir: '/downloads'
  }
};
modules/@apostrophecms/file/index.js

slugPrefix ​

Defaults to 'file-'. This prefix is applied to all file slugs to avoid collisions with other document types.

Fields ​

The file module adds the following fields to each file piece:

FieldTypeDescription
attachmentAttachmentRequired. The uploaded file. Accepts any file type in the configured file groups.
descriptionString (textarea)A description of the file.
creditStringAttribution credit for the file.
creditUrlURLA URL associated with the file credit.
_tagsRelationshipTags for organizing files, related to @apostrophecms/file-tag pieces.

Interesting properties ​

These properties are automatically available on file piece objects when they are loaded.

_url ​

Each file piece automatically receives a _url property containing a URL that can be used to download the file. If prettyUrls is enabled, this will be a human-readable URL; otherwise it will be the standard uploadfs URL for the attachment.

attachment ​

The attachment property contains the attachment object for the file. This object includes metadata such as the file extension, name, and size. It can be passed to apos.attachment.url() to generate a URL, although in most cases the _url property on the file piece itself is more convenient.