veliovgroup/Meteor-Files

πŸš€ Upload files via DDP or HTTP to β˜„οΈ Meteor server FS, AWS, GridFS, DropBox or Google Drive. Fast, secure and robust.

β˜… 1,116Forks 165JavaScriptGitHub β†—Compare

Project website β†—

aws-s3dropboxfile-sharingfile-uploadfilesgoogle-storagegridfshttpmeteormeteor-filesmeteor-packageuploadwebsockets

README

support support Mentioned in Awesome ostrio:files GitHub stars ostr.io meteor-files.com

Files for Meteor.js

Stable, fast, robust, and well-maintained Meteor.js package for files management using MongoDB Collection API. Call .insertAsync() method to initiate a file upload and to insert new record into MongoDB collection after upload is complete. Calling .removeAsync() method would erase stored file and record from MongoDB Collection. And so on, no need to learn new APIs. Hackable via hooks and events. Supports uploads to AWS:S3, GridFS, Google Storage, DropBox, and other 3rd party storage.

ToC:

Key features

Installation:

Install ostrio:files from Atmosphere

meteor add ostrio:files

Requires Meteor 3.2 or newer (v3.1.0 and later).

ES6 Import:

Import in isomorphic location (e.g. on server and client)

import { FilesCollection } from 'meteor/ostrio:files';

API overview

For detailed docs, examples, and API, read the documentation section.

Main methods:

  • FilesCollection Constructor [Isomorphic] - Initialize FilesCollection
  • insertAsync() [Client] - Upload a file to server, returns a Promise that resolves with the UploadInstance (FileUpload) when autoStart is true
  • link() [Isomorphic] - Generate downloadable link
  • find() [Isomorphic] - Find all files matching selector, returns FilesCursor instance
  • findOneAsync() [Isomorphic] - Find a single file record matching selector, returns FileCursor instance
  • removeAsync() [Isomorphic] - Asynchronously remove files from FilesCollection and "unlink" (e.g. remove) from Server
  • addFile() [Server] - Add local file to FilesCollection from FS
  • loadAsync() [Server] - Write file to FS and FilesCollection from remote URL
  • writeAsync() [Server] - Write Buffer to FS and FilesCollection

Constructor

[Isomorphic]. Initiate file's collection in the similar way to Mongo.Collection with optional settings related to file-uploads. Read full docs for FilesCollection Constructor in the API documentation.

import { FilesCollection } from 'meteor/ostrio:files';
new FilesCollection(FilesCollectionConfig);

Pass additional options to control upload-flow

// shared: /imports/lib/collections/images.collection.js
import { Meteor } from 'meteor/meteor';
import { FilesCollection } from 'meteor/ostrio:files';

const imagesCollection = new FilesCollection({
  collectionName: 'images',
  allowClientCode: false, // Disallow remove files from Client
  onBeforeUpload(file) {
    // Allow upload files under 10MB, and only in png/jpg/jpeg formats
    if (file.size <= 10485760 && /png|jpg|jpeg/i.test(file.extension)) {
      return true;
    }
    return 'Please upload image, with size equal or less than 10MB';
  }
});

if (Meteor.isClient) {
  // SUBSCRIBE TO ALL UPLOADED FILES ON THE CLIENT
  Meteor.subscribe('files.images.all');
}

if (Meteor.isServer) {
  // PUBLISH ALL UPLOADED FILES ON THE SERVER
  // Demo only: publishes every file record to every client. Filter by `userId` in production, see docs/security.md
  Meteor.publish('files.images.all', function () {
    return imagesCollection.collection.find();
  });
}

Upload a file

import { FilesCollection } from 'meteor/ostrio:files';
const files = new FilesCollection(FilesCollectionConfig);
files.insertAsync(config: InsertOptions, autoStart?: boolean): Promise<FileUpload | UploadInstance>;

Read full docs for insertAsync() method

Upload form (template):

<template name="uploadForm">
  {{#with currentUpload}}
    Uploading <b>{{file.name}}</b>:
    <span id="progress">{{progress.get}}%</span>
  {{else}}
    <input id="fileInput" type="file" />
  {{/with}}
</template>

Shared code:

import { FilesCollection } from 'meteor/ostrio:files';
const imagesCollection = new FilesCollection({collectionName: 'images'});
export default imagesCollection; // import in other files

Client's code:

import { Template } from 'meteor/templating';
import { ReactiveVar } from 'meteor/reactive-var';
Template.uploadForm.onCreated(function () {
  this.currentUpload = new ReactiveVar(false);
});

Template.uploadForm.helpers({
  currentUpload() {
    return Template.instance().currentUpload.get();
  }
});

Template.uploadForm.events({
  async 'change #fileInput'(e, template) {
    if (e.currentTarget.files && e.currentTarget.files[0]) {
      // We upload only one file, in case
      // multiple files were selected
      const upload = await imagesCollection.insertAsync({
        file: e.currentTarget.files[0],
        chunkSize: 'dynamic'
      }, false);

      upload.on('start', function () {
        template.currentUpload.set(this);
      });

      upload.on('end', function (error, fileObj) {
        if (error) {
          alert(`Error during upload: ${error}`);
        } else {
          alert(`File "${fileObj.name}" successfully uploaded`);
        }
        template.currentUpload.set(false);
      });

      await upload.start();
    }
  }
});

For multiple file upload see this demo code.

Upload base64 string (introduced in v1.7.1):

// As dataURI
await imagesCollection.insertAsync({
  file: 'data:image/png;base64,base64str…',
  isBase64: true, // <β€” Mandatory
  fileName: 'pic.png' // <β€” Mandatory
});

// As plain base64:
await imagesCollection.insertAsync({
  file: 'base64str…',
  isBase64: true, // <β€” Mandatory
  fileName: 'pic.png', // <β€” Mandatory
  type: 'image/png' // <β€” Mandatory
});

For more expressive example see Upload demo app

Stream files

To display files you can use fileURL template helper or link() method of FileCursor instance.

Template:

<template name='file'>
  <img src="{{imageFile.link}}" alt="{{imageFile.name}}" />
  <!-- Same as: -->
  <!-- <img src="{{fileURL imageFile}}" alt="{{imageFile.name}}" /> -->
  <hr>
  <video height="auto" controls="controls">
    <source src="{{videoFile.link}}?play=true" type="{{videoFile.type}}" />
    <!-- Same as: -->
    <!-- <source src="{{fileURL videoFile}}?play=true" type="{{videoFile.type}}" /> -->
  </video>
</template>

Shared code:

// imports/lib/collections/files.collection.js
import { Meteor } from 'meteor/meteor';
import { FilesCollection } from 'meteor/ostrio:files';

export const imagesCollection = new FilesCollection({ collectionName: 'images' });
export const videosCollection = new FilesCollection({ collectionName: 'videos' });

if (Meteor.isServer) {
  // Upload sample files on server's startup:
  Meteor.startup(async () => {
    await imagesCollection.loadAsync('https://raw.githubusercontent.com/veliovgroup/Meteor-Files/master/logo.png', {
      fileName: 'logo.png'
    });
    await videosCollection.loadAsync('https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4', {
      fileName: 'Big-Buck-Bunny.mp4'
    });
  });

  // Demo only: publishes every file record to every client. Filter by `userId` in production, see docs/security.md
  Meteor.publish('files.images.all', function () {
    return imagesCollection.collection.find();
  });

  Meteor.publish('files.videos.all', function () {
    return videosCollection.collection.find();
  });
} else {
  // Subscribe to file's collections on Client
  Meteor.subscribe('files.images.all');
  Meteor.subscribe('files.videos.all');
}

Client's code. The synchronous findOne() works on the Client only. Use findOneAsync() on the Server.

// imports/client/file/file.js
import { Template } from 'meteor/templating';
import '/imports/client/file/file.html';
import { imagesCollection, videosCollection } from '/imports/lib/collections/files.collection.js';

Template.file.helpers({
  imageFile() {
    return imagesCollection.findOne();
  },
  videoFile() {
    return videosCollection.findOne();
  }
});

For more expressive example see Streaming demo app

Download button

Create collection available to Client and Server

// imports/lib/collections/images.collection.js
import { Meteor } from 'meteor/meteor';
import { FilesCollection } from 'meteor/ostrio:files';
const imagesCollection = new FilesCollection({ collectionName: 'images' });
export default imagesCollection;

if (Meteor.isServer) {
  // Load sample image into FilesCollection on server's startup:
  Meteor.startup(async () => {
    await imagesCollection.loadAsync('https://raw.githubusercontent.com/veliovgroup/Meteor-Files/master/logo.png', {
      fileName: 'logo.png',
    });
  });

  // Demo only: publishes every file record to every client. Filter by `userId` in production, see docs/security.md
  Meteor.publish('files.images.all', function () {
    return imagesCollection.collection.find();
  });
} else {
  // Subscribe on the client
  Meteor.subscribe('files.images.all');
}

Create template, call .link method on the FileCursor returned from file helper

<!-- imports/client/file/file.html -->
<template name='file'>
  <a href="{{file.link}}?download=true" download="{{file.name}}" target="_parent">
    {{file.name}}
  </a>
</template>

Create controller for file template with file helper that returns FileCursor with .link() method

// imports/client/file/file.js
import { Template } from 'meteor/templating';
import '/imports/client/file/file.html';
import imagesCollection from '/imports/lib/collections/images.collection.js';

Template.file.helpers({
  file() {
    return imagesCollection.findOne();
  }
});

For more expressive example see Download demo

FAQ:

  1. Where are files stored by default?: by default if config.storagePath isn't set in Constructor options it equals assets/app/uploads/<collectionName> and is relative to the running script:
    • a. On development stage: yourDevAppDir/.meteor/local/build/programs/server. Note: All files will be removed as soon as your application rebuilds or you run meteor reset. To keep your storage persistent during development use an absolute path outside of your project folder, e.g. /data directory.
    • b. On production: yourProdAppDir/programs/server. Note: If using MeteorUp (MUP), Docker volumes must be added to mup.js, see MUP usage
  2. Cordova usage and development: To use Meteor-Files in a Cordova app, enable withCredentials; enable {allowQueryStringCookies: true} and {allowedCordovaOrigins: true} on both Client and Server (see security notes). For more details read Cookie's repository FAQ
  3. meteor-desktop usage and development: Meteor-Files can be used in meteor-desktop projects as well. As meteor-desktop works exactly like Cordova, all Cordova requirements and recommendations apply
  4. How to pause/continue upload and get progress/speed/remaining time?: see FileUpload instance returned from insertAsync method
  5. When using any of accounts packages - package accounts-base must be explicitly added to .meteor/packages above ostrio:files
  6. cURL/POST uploads - Take a look on POST-Example by @noris666
  7. In Safari (Mobile and Desktop) for DDP the algorithm reduces the chunk size, because Safari throws an error if a frame is too big. Switching to http transport (which has no such issue) is recommended for Safari. See #458
  8. Make sure you're using single domain for the Meteor app, and the same domain for hosting Meteor-Files endpoints, see #737 for details
  9. When requests are proxied to FilesCollection endpoint make sure protocol http/1.1 is used, see #742 for details

Awards:

GCAA award

Get Support:

Demo applications:

Fully-featured file-sharing app:

Other demos:

Related Packages:

Support Meteor-Files project:

Contribution:

  • Want to help? Please check issues for open and tagged as help wanted issues;
  • Want to contribute? Read and follow PR rules. All PRs are welcome on dev branch. Please, always give expressive description to your changes and additions.

Supporters:

We would like to thank everyone who supports this project

Contributors

dr-dimitrubratelefantjankapunktbryanlimypaulincaisalmanhasnis-olGariestharryadeldependabot[bot]huevoncitoPrinzhornelewis33vtoccomenelikecoagmanocallmembrolljeeexKAZUuepaminondmikkelkingOliverColemanjdmswongamos-whitewolfRezaRahemtolamacrozonexsyannrafaelcorreiapolimake-github-pseudonymous-againkakadais

Issues