How to fork an existing Meteorite package in a clean way?

Question

I'm trying to figure out the best/cleanest way to fork an existing package on Atmosphere within a project. I encountered a few occasions where an existing package needed some modifications and I was forced to fork it.

As far as I can tell, the following options exist. Unfortunately, all of these have their own issues and I have yet to find the perfect solution. I will use meteor-router as an example:

1. Simply copy the package files into your packages folder

Steps:

• remove packages/router/.git/
• edit packages/.gitignore and remove the 'router' line
• remove router from your smart.json
• add packages/router to your project repository and commit
• now make changes (this way your initial commit is a clean version and you can work out what you have changed yourself)

Advantages:

• easy to achieve and understand
• all the code you rely on can be found in your project repository

Disadvantages:

• you lose all the original repositories history
• it's hard to update to a newer version
• it's hard contribute your changes back to the original project

Do not even consider this for any but the simplest packages!

2. Fork on github, then ...

To fork a package on github, your can check your smart.lock file to see which repository is being used. Go to the github page of that repository and fork it.

Next, you have three options:

2a. Add it as a git submodule

More info on git submodules: http://git-scm.com/book/en/Git-Tools-Submodules

Steps:

• See the link above about how to init/create/update a submodule
• Remove the package from your smart.json

Advantages:

• Submodule versions are connected to your project
• Changes are immediately picked up

Disadvantages:

• All developers need to run git submodule init the first time and update to update
• You have to be aware of the issues with submodules when editing the checkout
• Read about other issues with submodules

2b. Edit your project's smart.json to use your version

Steps:

• In your smart.json, find "router": {} and add "git": "https://github.com/USER/meteor-router.git" inside the empty {}.
• Optionally, add a "branch" or "tag".

Advantages:

• You can still use Meteorite to manage your external packages
• Will work automatically for other developers and in deployment environments

Disadvantages:

• The code in your packages folder is not editable, as it's not a git repository
• Meteorite will not automatically update to the latest version every time your run it

(Suggested Meteorite improvement: allow packages to be installed in an editable form, like Python's pip allows using the '-e' parameter)

2c. Clone outside of your project and add a "path" to smart.json

Steps:

• Clone the package to a place outside of your project
• Similar to 2b, add a "path" to your smart.json to point Meteorite to your local checkout

Advantages:

• You can edit the package at will and Meteor will automatically pickup the changes.

Disadvantages:

• If you commit this smart.json, you will most likely break all other development/deployment environments...

---

Which method do you use? How do you work around the disadvantages to that method?

I might have missed some issues with these solutions.

Endocrinotherapy

Thanks for the guide! Any updates on how to do it now that Meteor has its own package repository? Thanks! – Muriel

This is the worst part of the Meteor DX experience. Npm does an amazing job at this. – Brunell

Answer 1

2b. Edit your project's smart.json to use your version

I would recommend this version, as it is the most consistent with how the smart.json was intended to be used and supported. mrt update will correctly reflect the latest from the git repo I think.

Beebe

Answer 2

For Meteor 1.0 I recommend the following:

1. Set up a local packages folder

   $ mkdir "$HOME/code/packages"
   

2. Add the PACKAGE_DIRS environment variable to your .bashrc/.zshrc file

   export PACKAGE_DIRS="$HOME/code/packages"
   

3. Fork and Clone the repository

   $ cd "$HOME/code/packages"
   $ git clone <yourGithubFork>
   

4. Install the package from your filesystem

   $ meteor add <packagenamespace>:<packagename>
   

Coper

This is the real answer – Excitability

How does this compare with the 'packages' folder approach (below) when deploying using Mup? – Brunell

Answer 3

There is an even easier answer than all of the above. Create a directory called packages in your project and put the package you want to override in it. Simple!

Ex: Let's say that you wanted to make some changes to accounts-ui-unstyled (which is a sub-dependency of accounts-ui) from meteor. Do a git clone of the entire meteor source to a local repository:

MyMachine:~ theuser$ cd Development/
MyMachine:Development theuser$ git clone https://github.com/meteor/meteor.git
MyMachine:Development theuser$ cp accounts-ui-unstyled ~/Development/MyProject/packages

In your project structure you would then have this

MyProject
 |
 -> client
 -> lib
 -> packages
    |
    -> accounts-ui-unstyled
 -> private
 -> public
 -> server
 -> tests

Any changes you make inside of MyProject/packages/accounts-ui-unstyled will now override the package.

Aldridge

Does this work if you want to remove a dependency of a package? For example the one I'm trying to modify requires jQuery UI. I want to strip that requirement out, can I override that or do I have to build my own package? – Futtock

It probably would work to put an empty project there called jQuery UI. – Aldridge

How does this compare with the PACKAGES_DIR approach (above) when deploying with Mup? – Brunell

It's different in the sense that the above will put the package into the dependencies folder where it will not be as obvious that it is overridden. The above will also make it so that it is harder to set break points and change code actively since you must do meteor add every time something changes. – Aldridge

Thank you Konrad and @GrantCermak. This was very helpful. I can also confirm that the solution works in Meteor 1.3 on Windows 7. Also it uploaded properly to my app on Galaxy. To add one more detail, I left the original atmosphere package name listed in .meteor/packages, but the forked version (in MyProject/packages) over-rode it perfectly, as hoped! (Not sure what the official view is on leaving the name listed in MyProject/packages.) – Doomsday

Answer 4

I use a hybrid of the #2 options: I point smart.json at a local checkout, but I put all of the packages, including the the app and the checked-out smart packages, as git submodules in a parent project. Meteorite still installs the rest of the smart packages in the app. This way, when you're developing the smart packages, everything stays consistent, and you can move your app to normal Meteorite when your fork gets merged.

See https://github.com/mizzao/CrisisMapping for an example. In my case, those aren't even forks, they are just smart packages that I am developing beyond the latest Meteorite release.

Goggler