A package is a directory with some code and a package.json file thatprovides information to Yarn about your package.
Most packages use some kind of version control system. The most common one isgit but Yarn doesn’t mind whatever one you choose to use. For this guide, ourexamples are going to use git.
Note: If you want to follow along with this guide, be sure to firstinstall gitand Yarn.
Creating your first package
In order to create your first package, open up your system terminal/console andrun the following commands:
git init my-new-projectcd my-new-projectyarn initThis is going to create a new git repository, put you inside of it, and thenopen up an interactive form for creating a new yarn project with the followingquestions:
name (my-new-project):version (1.0.0):description:entry point (index.js):git repository:author:license (MIT):You can type answers for each of these or you can just hit enter/return to usethe default or leave it blank.
Tip: If you want to use the defaults for everything you can also run
yarn init --yesand it will skip all the questions.
package.json
Now you should have a package.json that looks similar to this:
{ "name": "my-new-project", "version": "1.0.0", "description": "My New Project description.", "main": "index.js", "repository": { "url": "https://example.com/your-username/my-new-project", "type": "git" }, "author": "Your Name <[email protected]>", "license": "MIT"}The fields you see in the package.json have the following meanings:
- name is the identifier of your package, if you are going to publish it tothe global registry, you need to be sure that it is unique.
- version is the semver-compatible version of your package, you can publisha package as much as you want but they must have new versions.
- description is an optional but recommended field that gets used by otherYarn users to search for and understand your project.
- main s used to define the entry point of your code used by packagers or development environments as NodeJS. If unspecified it will default to
index.js. - repository is another optional but recommended field that helps users ofyour package find the source code to contribute back.
- author is the creator or maintainer of a package. It follows the format
"Your Name <[email protected]> (https://your-website.com)" - license is the published legal terms of your package and what is theallowed usage of the code in your package.
Today package.json supports the “exports” entry point which is taken over “main” entry point if it is defined.When you run
yarn init, all it is doing is creating this file, nothinghappens in the background. You can feel free to edit this file as much as youwant.
Additional fields
Let’s go through some additional package.json fields you might want to add.
{ "name": "my-new-project", "...": "...", "keywords": ["cool", "useful", "stuff"], "homepage": "https://my-new-project-website.com", "bugs": "https://github.com/you/my-new-project/issues", "contributors": [ "Your Friend <[email protected]> (https://their-website.com)", "Another Friend <[email protected]> (https://another-website.org)" ], "files": ["index.js", "lib/*.js", "bin/*.js"], "bin": { "my-new-project-cli": "bin/my-new-project-cli.js" }}- keywords is a list of terms that other developers can search for to findyour package or related packages.
- homepage is a url to point users to a website that informs them on thepackage with an introduction, documentations, and links to additionalresources.
- bugs is a url to point users of your package to if they discover an issuewith your package.
- contributors is a list of contributors to the package. If there are otherpeople involved in your project, you can specify them here.
- files is a list of files that should be included in your package whenpublished and installed. If unspecified Yarn will include every file.
- bin is a mapping of cli commands (binaries) for Yarn to create for thepackage when installing it.
For a complete list of all the package.json fields and more details abouteach of the above fields please see thepackage.json documentation.
Licensing and open source
Yarn packages are generally encouraged to beopen source, however it’s important tonote that they aren’t inherently open source by simply publishing them.
In order for code to be open source it needs to have an open source license.There are many open source licenses to choose from, here are a couple of commonones:
If you want more options, you can geta more complete list here.
When you select an open source license for your package, be sure to add aLICENSE file in the root of your package with the license text and updateyour package.json license field.
Note: If you do not want your project to be licensed as an open sourceproject, you should be explicit about what the licensing is or if it isunlicensed.
Code sharing
You will likely want to allow users of your package to be able to access yoursource code and have a way to report issues. There are a couple of popularwebsites for hosting your code:
These sites will allow your users to see your code, report issues, andcontribute back. Once you have your code up somewhere you should add thefollowing fields to your package.json:
{ "homepage": "https://github.com/username/my-new-project", "bugs": "https://github.com/username/my-new-project/issues", "repository": { "url": "https://github.com/username/my-new-project", "type": "git" }}Documentation
You should ideally write your documentation before you go publishing yourpackage. At a minimum you should write a README.md file in the root of yourproject that introduces your package and documents the public API.
Good documentation is defined by giving users all the knowledge they’ll need toget started with your project and continued use of it. Think about thequestions someone who knows nothing about your project will have. Describethings accurately and as detailed as necessary, but also try to keep it briefand easy to read. Projects with high quality documentation are far moresuccessful.
Keep packages small
When creating Yarn packages, you are encouraged to keep them small and simple.Break large packages into many small ones if it makes sense to do so. This ishighly encouraged as Yarn is capable of installing hundreds or even thousandsof packages very efficiently.
Many small packages are a great model of package management. Often this leadsto smaller download sizes because you aren’t bundling massive dependencies andonly using a small piece of it.
You should also consider the contents of your package. Make sure you aren’taccidentally distributing your tests or any other files that aren’t necessaryfor using your package (build scripts, images, etc).
Also be careful of what packages you are depending on, prefer smallerdependencies unless you have a good reason not to. Be certain that you aren’taccidentally depending on something massive.
As an enthusiast deeply immersed in the world of package management, particularly with Yarn and version control systems like Git, I bring a wealth of hands-on experience and in-depth knowledge to shed light on the concepts discussed in the provided article.
Version Control Systems (VCS): The article mentions that most packages use some form of version control system, with Git being the most common. I can attest to the significance of version control in software development, allowing for collaboration, tracking changes, and maintaining a history of project evolution. Git, as a distributed VCS, provides robust capabilities in managing code repositories.
Yarn and Package Management:
Yarn, a package manager, is emphasized in the article. I'm well-versed in Yarn's role in managing project dependencies efficiently. The process of initializing a new Yarn project, as demonstrated through commands like yarn init, is fundamental to setting up a project structure and generating the essential package.json file.
Package.json:
The article delves into the components of the package.json file. I understand that this file serves as a configuration manifest for a project. The fields within, such as "name," "version," and "description," play crucial roles in package identification, versioning, and project understanding. The significance of the "main" and "repository" fields in defining entry points and facilitating collaboration is well-explained.
Additional Fields in package.json:
The article expands on additional fields like "keywords," "homepage," and "bugs" in the package.json. I recognize the importance of these fields in enhancing discoverability, providing project-related information, and guiding users in issue reporting.
Licensing and Open Source:
The article emphasizes the importance of open-source licensing for Yarn packages. I am well aware of popular licenses such as MIT, Apache License 2.0, and GNU General Public License 3.0. The necessity to include a LICENSE file and update the license field in package.json is a crucial step in ensuring compliance with open-source practices.
Code Sharing and Hosting:
The article discusses code hosting platforms like GitHub, GitLab, and Bitbucket for sharing code and collaboration. I understand the value of including fields like "homepage" and "bugs" in package.json to guide users to relevant resources and issue tracking.
Documentation:
Documentation is highlighted as a key aspect of package development. I recognize the importance of providing comprehensive documentation, including a README.md file, to guide users and contributors. Clear and concise documentation is crucial for the success of a project.
Package Size and Dependency Management: The article advocates for keeping Yarn packages small and efficient. I understand the benefits of breaking down large packages, minimizing unnecessary files, and being mindful of dependencies to optimize download sizes and overall package management efficiency.
In conclusion, my expertise aligns seamlessly with the concepts discussed in the article, ensuring a thorough understanding of Yarn, version control systems, package.json configuration, open-source practices, code sharing, documentation, and efficient package management.
