Read Me
BEFORE YOU CONTINUE
Vulcan Meteor is considered a legacy. While it still being used in a few companies and projects, we do not advise starting a new project with it.
Instead, discover our new, shiny framework: Vulcan Next!
Vulcan Next is a port of Vulcan, using a more modern framework: Next.js. It includes similar features, but with a modern and scalable architecture.
Transition from Vulcan Meteor
If you were using Vulcan Meteor, check VulcanJS/vulcan-meteor-next-transition for a demonstration of using Vulcan Next for the frontend and an existing Vulcan Meteor app for the backend.
What's Vulcan?
Vulcan is a framework that gives you a set of tools for quickly building React & GraphQL-based web applications. It can handle data loading, e-mail notifications, automatic form generation, and much more, out of the box.
Note: you can find the old version of these docs (for pre-1.14 Vulcan) here.
Why Vulcan?
Vulcan is unique in that it spans the full-stack, from the database to the browser. While there exist many excellent back-end frameworks or backend-as-a-service providers, these all still require you to handle the front-end code yourself, including building a set of components to read, write, and display data.
However, being full-stack, Vulcan is able to speed up these repetitive tasks by providing a whole range of helper components that are fine-tuned to the Vulcan back-end, and as a result just work out of the box.
You can get a good overview of what Vulcan can do in the Features section.
Install
In order to run a Vulcan project, we'll need to first install Node and Meteor:
Install the latest version of Node and NPM. We recommend the usage of NVM.
You can then install Meteor, which is used as the Vulcan build tool.
Clone the Vulcan Starter repo locally.
Rename the
sample_settings.json
file tosettings.json
Run:
npm install
npm start
Troubleshooting Tip: If your app fails to start, try
meteor reset
npm start
And open http://localhost:3000/
in your browser. You'll then be presented with the first step of the “Getting Started” tutorial.
Note that you can also start the app with:
meteor --settings settings.json
All npm start
does is run the above command, while also checking for the presence of settings.json
first and creating it for you if it is missing.
(A note for windows
user: While running npm install
you might get an error regarding node-gyp
and bcrypt
package installation. This is because you need windows-build-tool for node-gyp
installation which is required for bcrypt
installation.)
Two-Repo Install (Optional)
In order to make working with Vulcan easier (especially when it comes to updating the core packages), you are also free to follow the more complicated "two-repo" pattern, with the two repositories being:
- Your own Vulcan project (for example, a clone of the Vulcan Starter project as outlined above).
- A clone of the main Vulcan repo, which the first repo will use as the source for the Vulcan core code.
Follow these steps to get set-up:
- Clone the main VulcanJS repo locally (for example, to
~/Vulcan
). - Create a new Meteor project or clone the Vulcan starter repo (this will become your project's repo).
- Inside your project repo, launch Vulcan with:
METEOR_PACKAGE_DIRS="/Users/sacha/Vulcan/packages" meteor --port 3000 --settings settings.json
(Taking care to adapt the /Users/sacha/Vulcan/packages
path to point to your Vulcan core repo's /packages
directory)
If you'd like, you can also export METEOR_PACKAGE_DIRS
as a global variable for all your Meteor apps. In your .bash_profile
file or equivalent, just add:
export METEOR_PACKAGE_DIRS="/Users/sacha/Vulcan/packages"
If you'd like to add more than one source directory (for example, one for Vulcan packages, and one for other Meteor packages), you can separate them with a :
:
export METEOR_PACKAGE_DIRS="/Users/sacha/Vulcan/packages:/Users/sacha/meteor-packages"
Git-Based Deploys
If you follow this install method, your Vulcan core files will not be included in the same Git repository as your "main" app. This can cause issues when using Git-based deploy methods such as Heroku. Either use deploy methods that bundle the whole app first (such as Meteor Up or Galaxy), or else add your core files as a Git submodule instead.
Getting Started
When you first run the Vulcan starter repo, you'll see the “Getting Started” tutorial and you should be able to follow along from there.
After that, you can also go through the Simple Example tutorial to get a grasp of how Vulcan's building blocks (data loading, forms, etc.) work.
At this stage, you can check out the example-forum
package to see what a full Vulcan app looks like, or the example-forms
example to learn more about Vulcan's forms system.
The Vulcan Core Package
Unless mentioned otherwise, all Vulcan utilities function are imported from the vulcan:core
Meteor package:
import { createCollection } from 'meteor/vulcan:core';
const Posts = createCollection({...});
Slack Channel
Vulcan has a pretty active Slack channel where you can ask for support, share ideas, and get tips.
Contribute
We're looking for contributors! If you're interested in this project, come say hello in the Vulcan Slack chatroom.