Hogyan készítsünk egy szép, apró, npm-es csomagot és tegyük közzé

Nem fogja elhinni, milyen könnyű ez!

Ha sok npm modult készített, ugorhat előre. Ellenkező esetben egy gyors bevezetőn megyünk keresztül.

TL; DR

Az npm modulhoz csak egy név és verzió tulajdonságokkal rendelkező package.json fájlra van szükség .

Hé!

Tessék.

Csak egy apró elefánt az egész életed előtted.

Nem vagy szakértő az npm csomagok készítésében, de szívesen megtanulnád, hogyan.

Az összes nagy elefánt óriási lábbal topog, csomagot készítve, és olyanok vagytok, mint:

- Ezzel nem tudok versenyezni.

Nos, azért vagyok itt, hogy elmondjam, hogy tudsz!

Nincs több önbizalom kétség.

Kezdjük!

Nem vagy elefánt

Ezt metaforikusan gondoltam.

Elgondolkodott már azon, hogy hívják az elefántcsecsemőket?

Természetesen van. Az elefántgyereket borjúnak hívják.

hiszek benned

Az önbizalom kétséges.

Ezért soha senki nem csinál semmi jót.

Azt hiszed, hogy nem fog sikerülni, ezért nem csinálsz semmit. De akkor dicsőíted az embereket, akik minden fantasztikus dolgot csinálnak.

Szuper ironikus.

Ezért megmutatom nektek a lehető legkisebb npm modult.

Nemsokára npm modulok repülnek ki az ujjainak hegyéből. Újrafelhasználható kód, ameddig a szem lát. Nincs trükk - nincsenek összetett utasítások.

A komplex utasítások

Megígértem, hogy nem fogom…

… De teljesen megtettem.

Nem is olyan rosszak. Egy napon megbocsátasz nekem.

1. lépés: npm számla

Kell egy. Ez csak az üzlet része.

Regisztrálj itt.

2. lépés: Bejelentkezés

Készített npm számlát?

Igen.

Menő.

Azt is feltételezem, hogy használhatja a parancssort / konzolt, stb. Mostantól terminálnak fogom hívni. Látszólag van egy különbség.

Menjen a termináljához, és írja be:

npm adduser

Használhatja a következő parancsot is:

npm login

Válassza ki azt a parancsot, amelyik vicces.

Kérni fogja a felhasználónév , a jelszó és az e-mail címet . Ragaszd őket oda!

Ehhez hasonló üzenetet kell kapnia:

Logged in as bamblehorse to scope @username on //registry.npmjs.org/.

Szép!

Készítsünk csomagot

Először szükségünk van egy mappára a kódunk tárolásához. Készítsen olyat, amelyik az Ön számára kényelmes. Aprónak hívom a csomagomat, mert valóban nagyon kicsi. Hozzáadtam néhány terminálparancsot azok számára, akik nem ismerik őket.

md tiny

Ebben a mappában szükségünk van egy package.json fájlra. Ha már használja a Node.js fájlt - korábban találkozott már ezzel a fájllal. Ez egy JSON fájl, amely információkat tartalmaz a projektjéről, és rengeteg különböző lehetőséggel rendelkezik. Ebben az oktatóanyagban csak kettőre fogunk koncentrálni.

cd tiny && touch package.json

Milyen kicsi lehet valójában?

Nagyon kicsi.

Az npm csomag készítésével kapcsolatos összes oktatóanyag, beleértve a hivatalos dokumentációt is, azt írja, hogy bizonyos mezőket kell megadnia a package.json fájlban. Addig próbáljuk a lehető legkevesebbet közzétenni a csomagunkat, amíg az nem működik. Ez egyfajta TDD egy minimális npm csomaghoz.

Please note: I’m showing you this to demonstrate that making an npm package doesn’t have to be complicated. To be useful to the community at large, a package needs a few extras, and we’ll cover that later in the article.

Publishing: First attempt

To publish your npm package, you run the well-named command: npm publish.

So we have an empty package.json in our folder and we’ll give it a try:

npm publish

Whoops!

We got an error:

npm ERR! file package.json npm ERR! code EJSONPARSE npm ERR! Failed to parse json npm ERR! Unexpected end of JSON input while parsing near '' npm ERR! File: package.json npm ERR! Failed to parse package.json data. npm ERR! package.json must be actual JSON, not just JavaScript. npm ERR! npm ERR! Tell the package author to fix their package.json file. JSON.parse

npm doesn’t like that much.

Fair enough.

Publishing: Strike two

Let’s give our package a name in the package.json file:

{ "name": "@bamlehorse/tiny" }

You might have noticed that I added my npm username onto the beginning.

What’s that about?

By using the name @bamblehorse/tiny instead of just tiny, we create a package under the scope of our username. It’s called a scoped package. It allows us to use short names that might already be taken, for example the tiny package already exists in npm.

You might have seen this with popular libraries such as the Angular framework from Google. They have a few scoped packages such as @angular/core and @angular/http.

Pretty cool, huh?

We’ll try and publish a second time:

npm publish

The error is smaller this time — progress.

npm ERR! package.json requires a valid “version” field

Minden npm csomagnak szüksége van egy verzióra, hogy a fejlesztők tudják, hogy biztonságosan tudnak-e frissíteni a csomag új kiadására anélkül, hogy feltörnék a többi kódot. Az npm verziószámú rendszer SemVer nevet viseli , amely a Semantic Versioning rövidítést jelenti .

Ne aggódjon túl sokat a bonyolultabb verziónevek megértése miatt, de az alábbiakban összefoglaljuk az alapvető működését:

A MAJOR.MINOR.PATCH verziószámmal növelje a következőket: 1. MAJOR verzió, amikor nem kompatibilis API-módosításokat hajt végre, 2. KISEBB verzió, ha visszafelé kompatibilis módon ad hozzá funkciókat, és PATCH verzió, ha visszafelé kompatibilis hibajavításokat végez. A kiadás előtti és a build-metaadatok további címkéi a MAJOR.MINOR.PATCH formátum kiterjesztéseként állnak rendelkezésre .//semver.org

Kiadás: A harmadik próbálkozás

Megadjuk a package.json verziónkat: 1.0.0 - az első nagyobb kiadás.

{ "name": "@bamblehorse/tiny", "version": "1.0.0" }

Tegyük közzé!

npm publish

Ó, ócska.

npm ERR! publish Failed PUT 402npm ERR! code E402npm ERR! You must sign up for private packages : @bamblehorse/tiny

Engedje meg, hogy elmagyarázzam.

A hatókörű csomagokat automatikusan privátban teszik közzé, mivel amellett, hogy hozzánk hasonló egyedi felhasználók számára hasznosak, a vállalatok is használják őket a projektek közötti kódmegosztáshoz. Ha normál csomagot tettünk volna közzé, akkor itt véget ér az utunk.

Csak annyit kell változtatnunk, hogy elmondjuk az npm-nek, hogy valójában azt akarjuk, hogy mindenki használja ezt a modult - ne tartsa elzárva a tárolóktól. Tehát inkább futunk:

npm publish --access=public

Bumm!

+ @bamblehorse/[email protected]

Pluszjelet, csomagunk nevét és verzióját kapjuk.

Megcsináltuk - az npm klubban vagyunk.

Izgatott vagyok.

Biztosan izgatott vagy.

Ezt elkapta?

npm szeret

Aranyos!

Az első verzió odakint van!

Csoportosítsunk át

If we want to be taken seriously as a developer, and we want our package to be used, we need to show people the code and tell them how to use it. Generally we do that by putting our code somewhere public and adding a readme file.

We also need some code.

Seriously.

We have no code yet.

GitHub is a great place to put your code. Let’s make a new repository.

README!

I got used to typing README instead of readme.

You don’t have to do that anymore.

It’s a funny convention.

We’re going to add some funky badges from shields.io to let people know we are super cool and professional.

Here’s one that let’s people know the current version of our package:

This next badge is interesting. It failed because we don’t actually have any code.

We should really write some code…

License to code

That title is definitely a James Bond reference.

I actually forgot to add a license.

A license just let’s people know in what situations they can use your code. There are lots of different ones.

There’s a cool page called insights in every GitHub repository where you can check various stats — including the community standards for a project. I’m going to add my license from there.

Then you hit this page:

The Code

We still don’t have any code. This is slightly embarrassing.

Let’s add some now before we lose all credibility.

module.exports = function tiny(string) { if (typeof string !== "string") throw new TypeError("Tiny wants a string!"); return string.replace(/\s/g, ""); };

There it is.

A tiny function that removes all spaces from a string.

So all an npm package requires is an index.js file. This is the entry point to your package. You can do it in different ways as your package becomes more complex.

But for now this is all we need.

Are we there yet?

We’re so close.

We should probably update our minimal package.json and add some instructions to our readme.md.

Otherwise nobody will know how to use our beautiful code.

package.json

{ "name": "@bamblehorse/tiny", "version": "1.0.0", "description": "Removes all spaces from a string", "license": "MIT", "repository": "bamblehorse/tiny", "main": "index.js", "keywords": [ "tiny", "npm", "package", "bamblehorse" ] }

We’ve added:

  • description: a short description of the package
  • repository: GitHub friendly — so you can write username/repo
  • license: MIT in this case
  • main: the entry point to your package, relative to the root of the folder
  • keywords: a list of keywords used to discover your package in npm search

readme.md

We’ve added instructions on how to install and use the package. Nice!

If you want a good template for your readme, just check out popular packages in the open source community and use their format to get you started.

Done

Let’s publish our spectacular package.

Version

First we’ll update the version with the npm version command.

This is a major release so we type:

npm version major

Which outputs:

v2.0.0

Publish!

Let’s run our new favorite command:

npm publish

It is done:

+ @bamblehorse/[email protected]

Cool stuff

Package Phobia gives you a great summary of your npm package. You can check out each file on sites like Unpkg too.

Thank you

That was a wonderful journey we just took. I hope you enjoyed it as much as I did.

Please let me know what you thought!

Star the package we just created here:

★ Github.com/Bamblehorse/tiny ★

Follow me on Twitter, Medium or GitHub