Hvordan man laver en smuk, lille npm-pakke og udgiver den

Du vil ikke tro, hvor let det er!

Hvis du har oprettet mange npm-moduler, kan du springe videre. Ellers gennemgår vi en hurtig introduktion.

TL; DR

Et npm-modul kræver kun en package.json-fil med navn og versionsegenskaber .

Hej!

Der er du.

Bare en lille elefant med hele dit liv foran dig.

Du er ingen ekspert i at fremstille npm-pakker, men du vil meget gerne lære hvordan.

Alle de store elefanter støder rundt med deres kæmpe fødder og laver pakke efter pakke, og I er alle som:

"Jeg kan ikke konkurrere med det."

Nå, jeg er her for at fortælle, at du kan!

Ikke mere selvtvivl.

Lad os begynde!

Du er ikke en elefant

Det mente jeg metaforisk.

Har du nogensinde spekuleret på, hvad baby elefanter hedder?

Selvfølgelig har du det. En baby elefant kaldes en kalv.

jeg tror på dig

Selvtillid er reel.

Derfor gør ingen nogensinde noget cool.

Du tror, ​​du ikke vil få succes, så i stedet gør du intet. Men så forherliger du folket, der laver alle de fantastiske ting.

Super ironisk.

Derfor vil jeg vise dig det mindste mulige npm-modul.

Snart har du masser af npm-moduler, der flyver ud af dine fingerspidser. Genanvendelig kode så langt øjet kan se. Ingen tricks - ingen komplekse instruktioner.

De komplekse instruktioner

Jeg lovede, at jeg ikke ville ...

... men det gjorde jeg helt.

De er ikke så dårlige. Du tilgiver mig en dag.

Trin 1: npm-konto

Du har brug for en. Det er bare en del af aftalen.

Tilmeld dig her.

Trin 2: login

Oprettede du en npm-konto?

Ja, det gjorde du.

Fedt nok.

Jeg antager også, at du kan bruge kommandolinjen / konsollen osv. Jeg kalder det terminalen fra nu af. Der er tilsyneladende en forskel.

Gå til din terminal og skriv:

npm adduser

Du kan også bruge kommandoen:

npm login

Vælg den kommando, der leverer med dig.

Du får en anmodning om dit brugernavn , din adgangskode og din e-mail . Stik dem derinde!

Du bør få en besked, der ligner denne:

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

Pæn!

Lad os lave en pakke

Først har vi brug for en mappe til at indeholde vores kode. Opret en, uanset hvilken måde der er behagelig for dig. Jeg kalder min pakke lille, fordi den virkelig er meget lille. Jeg har tilføjet nogle terminalkommandoer til dem, der ikke er fortrolige med dem.

md tiny

I den mappe har vi brug for en package.json- fil. Hvis du allerede bruger Node.js - har du mødt denne fil før. Det er en JSON-fil, der indeholder oplysninger om dit projekt og har en overflod af forskellige muligheder. I denne vejledning vil vi kun fokusere på to af dem.

cd tiny && touch package.json

Hvor lille kan det dog være?

Virkelig lille.

Alle vejledninger om oprettelse af en npm-pakke, inklusive den officielle dokumentation, fortæller dig at indtaste bestemte felter i din pakke.json. Vi vil fortsætte med at forsøge at udgive vores pakke med så lidt som muligt, indtil den fungerer. Det er en slags TDD til en minimal npm-pakke.

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

Hver npm-pakke har brug for en version, så udviklere ved, om de sikkert kan opdatere til en ny udgivelse af din pakke uden at bryde resten af ​​deres kode. Versioneringssystemet npm ved hjælp kaldes SemVer , som står for Semantic Versioning .

Du skal ikke bekymre dig for meget om at forstå de mere komplekse versionnavne, men her er deres resumé af, hvordan de grundlæggende fungerer:

Med et versionsnummer MAJOR.MINOR.PATCH øges: 1. STOR version, når du foretager uforenelige API-ændringer, 2. MINOR version, når du tilføjer funktionalitet bagudkompatibelt, og3. PATCH-version, når du foretager bagudkompatible fejlrettelser. Yderligere etiketter til pre-release og build-metadata er tilgængelige som udvidelser til MAJOR.MINOR.PATCH-formatet .//semver.org

Udgivelse: Det tredje forsøg

Vi giver vores package.json versionen: 1.0.0 - den første store udgivelse.

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

Lad os offentliggøre!

npm publish

Aw shucks.

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

Tillad mig at forklare.

Scoped-pakker offentliggøres automatisk privat, foruden at de er nyttige for enkeltbrugere som os, bruges de også af virksomheder til at dele kode mellem projekter. Hvis vi havde offentliggjort en normal pakke, ville vores rejse ende her.

Alt, hvad vi har brug for at ændre, er at fortælle npm, at vi faktisk ønsker, at alle skal bruge dette modul - ikke holde det låst væk i deres hvælvinger. Så i stedet løber vi:

npm publish --access=public

Boom!

+ @bamblehorse/[email protected]

Vi modtager et plustegn, navnet på vores pakke og versionen.

Vi gjorde det - vi er i npm-klubben.

Jeg er spændt.

Du må være begejstret.

Fang du det?

npm elsker dig

Sød!

Version 1 er derude!

Lad os omgruppere

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

Først opdaterer vi versionen med kommandoen npm version.

Dette er en stor udgivelse, så vi skriver:

npm version major

Hvilke output:

v2.0.0

Offentliggøre!

Lad os køre vores nye favoritkommando:

npm publish

Det er gjort:

+ @bamblehorse/[email protected]

Seje ting

Package Phobia giver dig et godt sammendrag af din npm-pakke. Du kan også tjekke hver fil på websteder som Unpkg.

tak skal du have

Det var en vidunderlig rejse, vi lige tog. Jeg håber, du nød det lige så godt som mig.

Lad mig vide, hvad du troede!

Star pakken, vi lige har oprettet her:

★ Github.com/Bamblehorse/tiny ★

Følg mig på Twitter, Medium eller GitHub