Awesome
Oyster Package Generator
Setting up a Unity package manager project with cloud builds, automated version numbers, and documentation can take days. Oyster Package Generator creates all of this for you by answering a few simple questions about your project. Save hundred of hours deploying and maintaining your Unity package by spending 15 minutes to setup and run Oyster.
Features
- Cloud deploy your Unity Package automatically to NPM
- Automatically generates the standard Unity package structure for you
- Version numbers are automatically created from your commits
- Auto-deploying nightly builds as you make commits
- Change logs are generated from commits
- Allows you to work inside a Unity project without cloning nested repos in
Assets
- Usable across platforms thanks to Node.js (Mac, Windows, Linux, ect.)
Support
Join the Discord Community if you have questions or need help.
Getting Started
In order to use Oyster Package Generator you'll need the following.
- Git installed
- Node.js version here installed
- GitHub account (uses GitHub specific deployment features)
- NPM account (used to publish packages)
Quick Start
If you just want a project generated run the following in a Unity repo.
npx oyster-package-generator init
If you want a step-by-step guide follow along below.
- Create a new Unity project and navigate to the root
- Setup Git (skip if already setup)
- Run
git init
to prep everything for Git - Run
git remote add origin YOUR_REPO
. ReplaceYOUR_REPO
with the proper repo URL (such as git@github.com:ashblue/oyster-package-generator.git). This needs to be done before oyster runs. Reason being it hard writes some Git addresses into your project
- Run
- Generate the Oyster package
- Run
npx oyster-package-generator init
and answer the prompts. Wait for the install script to finish. If you notice a bug on Windows 10 see here - Create your first commit with
npm run commit
. Choose "chore" and write "My first commit" for the body text - Run
git push
to deploy themaster
branch (follow on-screen instructions if prompted) - Use
git checkout -b develop
and then rungit push
to deploy it
- Run
- Setup cloud deploys (optional)
- Set your default GitHub branch to
develop
instead ofmaster
in your repo's settings. While not required, this will make pull requests and maintaining your repo easier
Once setup, all commits to the master
branch will generate a new release. All commits to the develop
branch will generate an unversioned nightly build.
Running the CLI
To generate your project you'll need to setup a GitHub repo if you haven't in a Unity project. Make sure you set the origin
remote as the origin is used to auto populate some of the files.
Run the following command and answer the question prompts.
npx oyster-package-generator init
Please note if you plan on using Oyster a lot (or on Windows 10) you should globally install it. npx
can be quite slow since it doesn't cache.
npm install -g oyster-package-generator
# Run the program
oyster init
You're done. If you want to setup cloud builds manually you'll need to do one extra thing.
Making commits to your project
All commits should be made with the following command. Your project will use Commitizen and enforce syntax via Commitlint.
npm run commit
Git Flow
You should install and use the Git Flow branching strategy when working with Oyster generated packages.
Why do I need GitFlow you might ask? Commits to Oyster's develop
branch automatically create nightly builds. Commits to master
automatically generate package releases. Therefore it's a good idea to work out of Git Flow's feature branches and use the branching strategy.
In short you must have a develop
and master
branch for cloud builds to work properly.
Windows 10 Troubleshooting
If you're on Windows 10 you may run into the username space bug in the filepath (example C:/first last/ect/...
). This is a known issue with npx
. You might just want to install the package globally with the following instead of trying to fix it.
npm install -g oyster-package-generator
# Run the program
oyster init
You may also want to consider installing Node.js in the root of your C drive to decrease any problems you might encounter. For example a new C:/node
folder during Node's setup.
Upgrading Older Projects
This package comes with a convenient feature to upgrade an older Oyster project to the latest version. Please consider the following before running the command.
- Make sure all changes are checked in, this will delete files
- After the process runs, check your Git diffs to make sure nothing was lost
- If you're upgrading from Travis CI to GitHub Actions you'll need to provide a new
NPM_TOKEN
in your repo's secrets - If you do not have a
.oyster.json
file (older projects), generate one with the generate-config command
When ready, use this command to trigger the upgrade.
npx oyster-package-generator upgrade
Generating a config
If you're on Oyster v1.X or v2.0, you'll need to generate a config file before running the upgrade
command. Configs are new as of version v2.1.0
. Generate a config file by running the following.
npx oyster-package-generator generate-config
GitHub Protected Branches
Due to a known bug with GitHub Action commits, it's not recommended to add special requirements to a master
protected branch. You can still protect master
, but special requirements will result in crashing the Semantic Release bot that auto deploys releases.
Licensing
Oyster Package Generator automatically includes an MIT license in the project. You can easily change this by deleting/changing the package.json
license key and the LICENSE.md
file if you desire.
Roadmap
To view the latest upcoming features you can check the roadmap here.
https://trello.com/b/Z9P0XMl6/oyster-package-generator
Setting up cloud builds
Follow the guide below to setup your tokens for automatic cloud deploys.
NPM Token
To get builds automatically deploying you'll need an NPM token. To get one we'll have to generate an authentication key and choose the "Automation" token type. You must have an npm account to generate a token.
Add the key to your repo secrets as NPM_TOKEN
.
Next we'll setup a GitHub token with admin privileges.
GitHug Token
Next you'll need to setup a GitHub token. While GitHub does provide a token by default to repos. We can't really use it here. Reason being branch protection privileges will stop important automatic updates when you try to release. Causing the release to fail.
First navigate to the personal access token menu by following these instructions. Check the repo box for permissions then create the token.
Add the key to your repo secrets as GH_TOKEN
.
Development Environment
To run this project locally you'll need to clone this repo and run the following in your project root. NVM is recommended to sync your local Node.js version. Or you can install the .nvmrc file version directly from the Node.js site. Please note the version of Node.js you use is important.
# If using NVM
nvm use
npm install
npm run build
After the processes are complete, you'll need to setup the oyster command locally to test it. This is important since you probably want to execute the command in various Unity projects. We can easily do this by running the following.
npm link
When the link is complete you can run oyster
in the terminal. Which will execute the last build created from npm run build
.
If you ever want to remove the global oyster
command just run the following in the project root. This will remove the command entirely and uninstall it.
npm unlink
Auto Builds
While developing, you may want to automatically rebuild the app when changes are detected. To do so simply run the following command that will automatically listen for changes.
npm run dev
Pull Requests / Contributing
Please see the Contributing Guidelines document for more info.