{"id":13951118,"url":"https://github.com/ashblue/oyster-package-generator","last_synced_at":"2025-04-10T21:21:10.281Z","repository":{"id":34984764,"uuid":"193552911","full_name":"ashblue/oyster-package-generator","owner":"ashblue","description":"Oyster is a package generator for Unity Package Manager (UPM). It generates a best standards Unity package with automated deployments via CLI. Focus on coding your package instead of deployments, changelogs, ect.","archived":false,"fork":false,"pushed_at":"2023-07-18T20:08:51.000Z","size":2326,"stargazers_count":27,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-04-01T00:01:50.340Z","etag":null,"topics":["cli","commitizen","generator","git-flow","package-generator","unity","unity-package-manager","unity3d","upm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashblue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ashblue","patreon":null,"open_collective":null,"ko_fi":"ashblue","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2019-06-24T17:50:42.000Z","updated_at":"2025-03-06T22:11:50.000Z","dependencies_parsed_at":"2024-09-29T06:19:14.474Z","dependency_job_id":null,"html_url":"https://github.com/ashblue/oyster-package-generator","commit_stats":{"total_commits":101,"total_committers":4,"mean_commits":25.25,"dds":"0.18811881188118806","last_synced_commit":"c4890fc568b30d0ca845d0c7173bff7732e84e0b"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Foyster-package-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Foyster-package-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Foyster-package-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashblue%2Foyster-package-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashblue","download_url":"https://codeload.github.com/ashblue/oyster-package-generator/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248298973,"owners_count":21080445,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","commitizen","generator","git-flow","package-generator","unity","unity-package-manager","unity3d","upm"],"created_at":"2024-08-08T06:01:13.992Z","updated_at":"2025-04-10T21:21:10.264Z","avatar_url":"https://github.com/ashblue.png","language":"TypeScript","funding_links":["https://github.com/sponsors/ashblue","https://ko-fi.com/ashblue"],"categories":["TypeScript"],"sub_categories":[],"readme":"# Oyster Package Generator\n\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\nSetting 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.\n\n![Oyster Package Generator CLI](docs/cli-example.png)\n\nFeatures\n\n* Cloud deploy your Unity Package automatically to NPM\n* Automatically generates the standard Unity [package structure](https://docs.unity3d.com/Manual/cus-layout.html) for you\n* Version numbers are automatically created from your commits\n* Auto-deploying nightly builds as you make commits\n* Change logs are generated from commits\n* Allows you to work inside a Unity project without cloning nested repos in `Assets`\n* Usable across platforms thanks to Node.js (Mac, Windows, Linux, ect.)\n\n**Support**\n\nJoin the [Discord Community](https://discord.gg/8QHFfzn) if you have questions or need help.\n\n# Getting Started\n\nIn order to use Oyster Package Generator you'll need the following.\n\n* [Git](https://git-scm.com/) installed\n* [Node.js](https://nodejs.org/en/) version [here](.nvmrc) installed\n* [GitHub](https://github.com/) account (uses GitHub specific deployment features)\n* [NPM](https://www.npmjs.com/) account (used to publish packages)\n\n## Quick Start\n\nIf you just want a project generated run the following in a Unity repo.\n\n```bash\nnpx oyster-package-generator init\n```\n\nIf you want a step-by-step guide follow along below.\n\n1. Create a new Unity project and navigate to the root\n2. Setup Git (skip if already setup)\n    1. Run `git init` to prep everything for Git\n    2. Run `git remote add origin YOUR_REPO`. Replace `YOUR_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\n3. Generate the Oyster package\n    1. 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](#windows-10-troubleshooting)\n    2. Create your first commit with `npm run commit`. Choose \"chore\" and write \"My first commit\" for the body text\n    3. Run `git push` to deploy the `master` branch (follow on-screen instructions if prompted)\n    4. Use `git checkout -b develop` and then run `git push` to deploy it\n4. [Setup cloud deploys](#setting-up-cloud-builds) (optional)\n5. Set your default GitHub branch to `develop` instead of `master` in your repo's settings. While not required, this will make pull requests and maintaining your repo easier\n\nOnce setup, all commits to the `master` branch will generate a new release. All commits to the `develop` branch will generate an unversioned nightly build.\n\n## Running the CLI\n\nTo 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.\n\nRun the following command and answer the question prompts.\n\n```bash\nnpx oyster-package-generator init\n```\n\nPlease note if you plan on using Oyster a lot (or on [Windows 10](#windows-10-troubleshooting)) you should globally install it. `npx` can be quite slow since it doesn't cache.\n\n```bash\nnpm install -g oyster-package-generator\n\n# Run the program\noyster init\n```\n\nYou're done. If you want to [setup cloud builds manually](#setting-up-cloud-builds) you'll need to do one extra thing.\n\n### Making commits to your project\n\nAll commits should be made with the following command. Your project will use [Commitizen](https://github.com/commitizen/cz-cli) and enforce syntax via [Commitlint](https://commitlint.js.org).\n\n```bash\nnpm run commit\n```\n\n### Git Flow\n\nYou should install and use the [Git Flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) branching strategy when working with Oyster generated packages. \n\nWhy 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.\n\nIn short **you must** have a `develop` and `master` branch for cloud builds to work properly.\n\n### Windows 10 Troubleshooting\n\nIf 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](https://github.com/zkat/npx/issues/146) with `npx`. You might just want to install the package globally with the following instead of trying to fix it.\n\n```bash\nnpm install -g oyster-package-generator\n\n# Run the program\noyster init\n```\n\nYou 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.\n\n### Upgrading Older Projects\n\nThis package comes with a convenient feature to upgrade an older Oyster project to the latest version. Please consider the following before running the command.\n\n* Make sure all changes are checked in, this will delete files\n* After the process runs, check your Git diffs to make sure nothing was lost\n* If you're upgrading from Travis CI to GitHub Actions you'll need to provide a new `NPM_TOKEN` in your repo's [secrets](https://docs.github.com/en/actions/reference/encrypted-secrets)\n* If you do not have a `.oyster.json` file (older projects), generate one with the [generate-config](#generating-a-config) command\n\nWhen ready, use this command to trigger the upgrade.\n\n```bash\nnpx oyster-package-generator upgrade\n```\n\n#### Generating a config\n\nIf 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.\n\n```bash\nnpx oyster-package-generator generate-config\n```\n\n### GitHub Protected Branches\n\nDue 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.\n\n### Licensing\n\nOyster 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.\n\n## Roadmap\n\nTo view the latest upcoming features you can check the roadmap here.\n\nhttps://trello.com/b/Z9P0XMl6/oyster-package-generator\n\n## Setting up cloud builds\n\nFollow the guide below to setup your tokens for automatic cloud deploys.\n\n### NPM Token\n\nTo get builds automatically deploying you'll need an NPM token. To get one we'll have to [generate an authentication key](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) and choose the \"Automation\" token type. You must have an [npm](https://www.npmjs.com) account to generate a token. \n\nAdd the key to your repo [secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository) as `NPM_TOKEN`.\n\nNext we'll setup a GitHub token with admin privileges.\n\n### GitHug Token\n\nNext 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.\n\nFirst navigate to the personal access token menu by following these [instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Check the repo box for permissions then create the token.\n\nAdd the key to your repo [secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository) as `GH_TOKEN`.\n\n## Development Environment\n\nTo run this project locally you'll need to clone this repo and run the following in your project root. [NVM](https://github.com/nvm-sh/nvm) is recommended to sync your local Node.js version. Or you can install the [.nvmrc](.nvmrc) file version directly from the [Node.js](https://nodejs.org/) site. Please note the version of Node.js you use is important.\n\n```bash\n# If using NVM\nnvm use\n\nnpm install\nnpm run build\n```\n\nAfter 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.\n\n```bash\nnpm link\n```\n\nWhen the link is complete you can run `oyster` in the terminal. Which will execute the last build created from `npm run build`.\n\nIf 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.\n\n```bash\nnpm unlink\n```\n\n### Auto Builds\n\nWhile 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.\n\n```bash\nnpm run dev\n```\n\n### Pull Requests / Contributing\n\nPlease see the [Contributing Guidelines](CONTRIBUTING.md) document for more info.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashblue%2Foyster-package-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashblue%2Foyster-package-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashblue%2Foyster-package-generator/lists"}