Πώς να δημιουργήσετε ένα προσαρμοσμένο γάντζο React και να το δημοσιεύσετε σε npm

Οι γάντζοι είναι μια εύχρηστη προσθήκη στο React API που μας επιτρέπει να οργανώσουμε μέρος της λογικής και της κατάστασής μας σε στοιχεία λειτουργίας. Πώς μπορούμε να δημιουργήσουμε ένα προσαρμοσμένο γάντζο και να το μοιραστούμε με τον υπόλοιπο κόσμο;

  • Τι είναι τα άγκιστρα;
  • Γιατί τα προσαρμοσμένα άγκιστρα είναι δροσερά;
  • Τι θα κάνουμε;
  • Βήμα 0: Ονομασία του γάντζου σας
  • Βήμα 1: Ρύθμιση του έργου σας
  • Βήμα 2: Σύνταξη του νέου σας React Hook
  • Βήμα 3: Χρησιμοποιώντας το γάντζο React σε ένα παράδειγμα
  • Βήμα 4: Σύνταξη του γάντζου και του παραδείγματος React
  • Βήμα 5: Δημοσίευση του γάντζου React σε npm
  • Περισσότεροι πόροι για τα άγκιστρα

Τι είναι τα άγκιστρα;

Οι γάντζοι αντιδράσεων με απλούς όρους είναι λειτουργίες. Όταν τα συμπεριλαμβάνετε στο εξάρτημα ή σε άλλο άγκιστρο, σας επιτρέπουν να κάνετε χρήση των εσωτερικών React και τμημάτων του κύκλου ζωής του React με γηγενείς γάντζους όπως useStateκαι useEffect.

Δεν σκοπεύω να κάνω μια βαθιά βουτιά για τα άγκιστρα, αλλά μπορείτε να δείτε μια γρήγορη εισαγωγή με ένα παράδειγμα useStateκαθώς και την εισαγωγή από την ομάδα του React.

Γιατί τα προσαρμοσμένα άγκιστρα είναι δροσερά;

Το σπουδαίο πράγμα για τη δημιουργία προσαρμοσμένων αγκιστριών είναι ότι σας επιτρέπουν να αφαιρέσετε τη λογική για τα στοιχεία σας, διευκολύνοντας την επαναχρησιμοποίηση σε πολλά στοιχεία της εφαρμογής σας.

Για παράδειγμα, εάν θέλετε να δημιουργήσετε έναν απλό μετρητή όπου χρησιμοποιείτε την κατάσταση του React για να διαχειριστείτε τον τρέχοντα αριθμό. Αντί να έχετε το ίδιο useStateάγκιστρο σε κάθε αρχείο συστατικών, μπορείτε να δημιουργήσετε αυτήν τη λογική μία φορά σε ένα useCounterάγκιστρο, καθιστώντας ευκολότερη τη συντήρηση, την επέκταση και τα σφάλματα σκουός εάν εμφανιστούν.

Τι θα κάνουμε;

Για τους σκοπούς αυτού του άρθρου, θα το κρατήσουμε απλό με ένα βασικό άγκιστρο. Συνήθως, μπορείτε να χρησιμοποιήσετε ένα άγκιστρο, επειδή αντί για μια τυπική λειτουργία, χρησιμοποιείτε άλλα εγγενή άγκιστρα που απαιτείται να χρησιμοποιηθούν στα στοιχεία της λειτουργίας React. Θα διατηρήσουμε κάποια βασική είσοδο και έξοδο για να διατηρήσουμε τα πράγματα απλά.

Θα δημιουργήσουμε ξανά αυτό το προσαρμοσμένο άγκιστρο Placecage που έφτιαξα, το οποίο σας επιτρέπει να δημιουργείτε εύκολα διευθύνσεις URL εικόνας που μπορείτε να χρησιμοποιήσετε ως εικόνες κράτησης θέσης.

Εάν δεν είστε εξοικειωμένοι, το Placecage είναι ένα API που σας επιτρέπει να δημιουργείτε εικόνες του Nic Cage ως εικόνες κράτησης θέσης για τον ιστότοπό σας. Ανόητος? Ναί. Διασκέδαση? Απολύτως!

Αλλά εάν δεν είστε οπαδός του έργου του Nic, μπορείτε να αλλάξετε εύκολα τη διεύθυνση URL για το Fill Murray που χρησιμοποιεί εικόνες του Bill Murray ή του placeholder.com που δημιουργεί απλό συμπαγές χρώμα φόντου με κείμενο που δείχνει το μέγεθος της εικόνας.

Βήμα 0: Ονομασία του γάντζου σας

Πριν προχωρήσουμε στον πραγματικό κώδικα, ο απώτερος στόχος μας είναι να δημοσιεύσουμε αυτό το άγκιστρο. Εάν αυτός δεν είναι ο στόχος σας, μπορείτε να παραλείψετε αυτό το βήμα, αλλά για δημοσίευση, θα θέλαμε να δημιουργήσουμε ένα όνομα για το άγκιστρο μας.

Στην περίπτωσή μας, το όνομα του αγκίστρου μας θα είναι usePlaceCage. Έχοντας αυτό κατά νου, έχουμε 2 μορφές του ονόματός μας - μία σε μορφή camelCase και μία σε μορφή περίπτωσης φιδιού.

  • camelCase: usePlaceCage
  • θήκη φιδιού: χρήση-πλακάτ

Η μορφή camelCase θα χρησιμοποιηθεί για την πραγματική λειτουργία αγκίστρου, όπου το όνομα της θήκης φιδιού θα χρησιμοποιηθεί για το όνομα του πακέτου και ορισμένους από τους φακέλους. Κατά τη δημιουργία του ονόματος, λάβετε υπόψη ότι το όνομα του πακέτου πρέπει να είναι μοναδικό. Εάν υπάρχει ήδη πακέτο με το ίδιο όνομα στο npmjs.com, δεν θα μπορείτε να το χρησιμοποιήσετε.

Εάν δεν έχετε ήδη όνομα, είναι εντάξει! Μπορείτε απλά να χρησιμοποιήσετε το δικό σας όνομα ή κάτι που μπορείτε να σκεφτείτε, δεν έχει σημασία πολύ, καθώς πραγματικά προσπαθούμε να μάθουμε πώς να το κάνουμε αυτό. Αν ήμουν για παράδειγμα, θα χρησιμοποιούσα:

  • camelCase: useColbysCoolHook
  • θήκη φιδιού: use-colbyscoolhook

Αλλά για να ξεκαθαρίσουμε, για το υπόλοιπο παράδειγμα, θα παραμείνουμε usePlaceCageκαι use-placecage.

Βήμα 1: Ρύθμιση του έργου σας

Αν και μπορείτε να ρυθμίσετε το έργο σας όπως θέλετε, θα ξεκινήσουμε να χτίζουμε ένα νέο γάντζο από αυτό το πρότυπο που δημιούργησα.

Η ελπίδα εδώ είναι ότι μπορούμε να πάρουμε μερικά από τα οδυνηρά κομμάτια της διαδικασίας και να γίνουμε αμέσως παραγωγικοί με το προσαρμοσμένο γάντζο μας. Μην ανησυχείτε όμως, θα εξηγήσω τι συμβαίνει στην πορεία.

Οι απαιτήσεις εδώ είναι το git και το νήμα καθώς βοηθά στην παροχή εργαλείων που διευκολύνουν το ικρίωμα αυτού του προτύπου, όπως η χρήση του χώρου εργασίας για να επιτρέπουν σε εύχρηστα σενάρια npm να διαχειρίζονται τον κώδικα από τη ρίζα του έργου. Εάν ένα από αυτά είναι ένα πρόγραμμα αντιμετώπισης προβλημάτων, μπορείτε να δοκιμάσετε να κατεβάσετε το repo μέσω του συνδέσμου λήψης και να το ενημερώσετε όπως απαιτείται.

Κλωνοποίηση του προτύπου αγκίστρου από το git

Για να ξεκινήσετε, ας κλωνοποιήσουμε το αποθετήριο από το Github. Στην παρακάτω εντολή, θα πρέπει να αντικαταστήσετε use-my-custom-hookμε το όνομα του γάντζου σας, όπως use-cookiesή use-mooncake.

git clone //github.com/colbyfayock/use-custom-hook use-my-custom-hook cd use-my-custom-hook 

Μόλις κλωνοποιήσετε και μεταβείτε σε αυτόν το φάκελο, θα πρέπει τώρα να δείτε 2 καταλόγους - έναν exampleκατάλογο και έναν use-custom-hookκατάλογο.

Αυτό θα σας δώσει μερικά πράγματα για να ξεκινήσετε:

  • Ένας κατάλογος αγκιστριών που θα περιλαμβάνει την πηγή του αγκίστρου μας
  • Δημιουργήστε σενάρια που συνθέτουν το γάντζο μας με το Babel
  • Ένα παράδειγμα σελίδας που εισάγει το άγκιστρο και δημιουργεί μια απλή σελίδα επίδειξης με το next.js

Εκτέλεση σεναρίων ρύθμισης αγκίστρου

Αφού κλωνοποιήσουμε με επιτυχία το repo, θέλουμε να εκτελέσουμε τα σενάρια εγκατάστασης που εγκαθιστούν εξαρτήσεις και να ενημερώσουν το άγκιστρο στο όνομα που θέλουμε.

yarn install && yarn setup 

Όταν εκτελείται το σενάριο εγκατάστασης, θα κάνει μερικά πράγματα:

  • It will ask you for your name – this is used to update the LICENSE and the package's author name
  • It will ask you for your hook's name in 2 variations – camelCase and snake-case - this will be used to update the name of the hook throughout the template and move files with that name to the correct location
  • It will reset git – it will first remove the local .git folder, which contains the history from my template and reinitialize git with a fresh commit to start your new history in
  • Finally, it will remove the setup script directory and remove the package dependencies that were only being used by those scripts

Starting the development server

Once the setup scripts finish running, you'll want to run:

yarn develop 

This runs a watch process on the hook source, building the hook locally each time a source file is changed, and running the example app server, where you can test the hook and make changes to the example pages.

With this all ready, we can get started!

Follow along with the commit!

Step 2: Writing your new React Hook

At this point, you should now have a new custom hook where you can make it do whatever you'd like. But since we're going to walk through rebuilding the usePlaceCage hook, let's start there.

The usePlaceCage hook does 1 simple thing from a high level view – it takes in a configuration object and returns a number of image URLs that you can then use for your app.

Just as a reminder, any time I mention usePlaceCage or use-placecage, you should use the hook name that you set up before.

A little bit about placecage.com

Placecage.com is a placeholder image service that does 1 thing. It takes a URL with a simple configuration and returns an image... of Nic Cage.

From the simplest use, the service uses a URL pattern as follows:

//www.placecage.com/200/300 

This would return an image with a width of 200 and height of 300.

Optionally, you can pass an additional URL parameter that defines the type of image:

//www.placecage.com/gif/200/300 

In this particular instance, our type is gif, so we'll receive a gif.

The different types available to use are:

  • Nothing: calm
  • g: gray
  • c: crazy
  • gif: gif

We'll use this to define how we set up configuration for our hook.

Defining our core generator function

To get started, we're going to copy over a function at the bottom of our use-placecage/src/usePlaceCage.js file, which allows us to generate an image URL, as well as a few constant definitions that we'll use in that function.

First, let's copy over our constants to the top of our usePlaceCage.js file:

const PLACECAGE_HOST = '//www.placecage.com/'; const TYPES = { calm: null, gray: 'g', crazy: 'c', gif: 'gif' }; const DEFAULT_TYPE = 'calm'; const ERROR_BASE = 'Failed to place Nick'; 

Here we:

  • Define a host, which is the base URL of our image service.
  • Define the available types, which we'll use in the configuration API. We set calm to null, because it's the default value which you get by not including it at all
  • Our default type will be calm
  • And we set an error base which is a consistent message when throwing an error

Then for our function, let's copy this at the bottom of our usePlaceCage.js file:

function generateCage(settings) { const { type = DEFAULT_TYPE, width = 200, height = 200, count = 1 } = settings; const config = []; if ( type !== DEFAULT_TYPE && TYPES[type] ) { config.push(TYPES[type]); } config.push(width, height); if ( isNaN(count) ) { throw new Error(`${ERROR_BASE}: Invalid count ${count}`); } return [...new Array(count)].map(() => `${PLACECAGE_HOST}${config.join('/')}`); } 

Walking through this code:

  • We define a generateCage function which we'll use to generate our image URL
  • We take in a settings object as an argument, which defines the configuration of our image URL. We'll be using the same parameters as we saw in our placecage.com URL
  • We destructure those settings to make them available for us to use
  • We have a few defaults here just to make it easier. Our default type will be defined by DEFAULT_TYPE along with a default width, height, and number of results we want to return
  • We create a config array. We'll use this  to append all of the different configuration objects in our URL and finally join them together with a / essentially making a URL
  • Before we push our config to that array, we check if it's a valid argument, by using the TYPES object to check against it. If it's valid, we push it to our config array
  • We then push our width and height
  • We do some type checking, if we don't have a valid number as the count, we throw an error, otherwise we'll get incorrect results
  • Finally, we return a new array with the number of results requested, mapped to a URL creator, which uses PLACECAGE_HOST as our defined base URL, and with our config array joined by /

And if we were to test this function, it would look like this:

const cage = generateCage({ type: 'gif', width: 500, height: 500, count: 2 }); console.log(cage); // ['//www.placecage.com/gif/500/500', '//www.placecage.com/gif/500/500']

Using our function in the hook

So now that we have our generator function, let's actually use it in our hook!

Inside of the usePlaceCage function in the use-placecage/src/usePlaceCage.js file, we can add:

export default function usePlaceCage (settings = {}) { return generateCage(settings); } 

What this does it uses our generator function, takes in the settings that were passed into the hook, and returns that value from the hook.

Similar to our previous use example, if we were to use our hook, it would look like this:

const cage = usePlaceCage({ type: 'gif', width: 500, height: 500, count: 2 }); console.log(cage); // ['//www.placecage.com/gif/500/500', '//www.placecage.com/gif/500/500'] 

At this point, it does the same thing!

So now we have our hook, it serves as a function to generate image URLs for the placecage.com service. How can we actually use it?

Follow along with the commit!

Step 3: Using your React hook in an example

The good news about our template, is it already includes an example app that we can update to easily make use of our hook to both test and provide documentation for those who want to use it.

Setting up the hook

To get started, let's open up our example/pages/index.js file. Inside of this file you'll see the following:

const hookSettings = { message: 'Hello, custom hook!' } const { message } = usePlaceCage(hookSettings); 

This snippet is what was used by default in the template just for a proof of concept, so let's update that. We're going to use the same exact configuration as we did in Step 2:

const hookSettings = { type: 'gif', width: 500, height: 500, count: 2 } const cage = usePlaceCage(hookSettings); 

Again, we set up our settings object with the configuration for our hook and invoke our hook and set the value to the cage constant.

If we now console log that value our to our dev tools, we can see it working!

console.log('cage', cage); 

Note: If you get an error here about message, you  can comment that our or remove it under the Examples section.

Updating the example with our new hook configuration

If you scroll down to the Examples section, you'll notice that we have the same default hookSettings as above, so let's update that again to make sure our example is accurate.

{`const hookSettings = { type: 'gif', width: 500, height: 500, count: 2 } const cage = usePlaceCage(hookSettings);`} 

You'll also notice that we're no longer using the message variable. If you didn't remove it in the last step, we can now replace it under the Output heading with:

{ JSON.stringify(cage) }

{ cage.map((img, i) =>)}

We're doing 2 things here:

  • Instead of showing the variable itself, we wrap it with JSON.stringify so that we can show the contents of the array
  • We also use the map function to loop over our image URLs in the cage constant and create a new image element for each. This let's us preview the output instead of just seeing the values

And once you save and open your browser, you should now see your updated examples and output!

Other things you can do on that page

Before moving on, you can also update a few other things that will be important for your hooks page:

  • Update the How to use section with instructions
  • Add additional examples to make it easier for people to know what to do

A  few things are also automatically pulled in from the use-placecage/package.json file. You can either update them there to make it easier to maintain or you can replace them in the example page:

  • name: Is used at the

    of the page

  • description: Is used at the description under the

  • repository.url: Used to include a link to the repository
  • author: The name and url are used to include a link at the bottom of the page

Follow along with the commit!

Step 4: Compiling your React hook and Example

The way we can make our hook work easily as an npm module is to compile it for others to use. We're using babel to do this.

Though the publish process already does this for us automatically with the prepublishOnly script in use-placecage/package.json, we can manually compile our hook using the yarn build command from the root of the project.

Along with compiling the hook, running yarn build will also compile the example page, allowing you to upload it wherever you'd like. After running that command, you should see an output of static HTML files in the example/out directory.

If you're looking for a recommendation, Netlify makes it easy to connect your Github account and deploy the static site.

See the demo site deployed to Netlify!

Step 5: Publishing your React hook to npm

Finally, if you're happy with your hook, it's time to publish!

npm makes this part really easy. The only prerequisite you need to have an npm account. With that account, let's log in:

npm login 

Which will prompt you for your login credentials.

Next, let's navigate to our hook's directory, as our package configuration is there under use-placecage/package.json:

cd use-placecage 

Then, we can simply publish!

npm publish 

Keep in mind, that each package name needs to be unique. If you used use-placecage, it's already taken... by me. ?

But if you're successful, npm should build your hook and upload it to the package registry!

It will then be available on npm with the following pattern:

//www.npmjs.com/package/[package-name] 

So for use-placeage, it's available here: //www.npmjs.com/package/use-placecage

We now have a custom hook!

Yay ? if you followed along, you should now have created a custom hook and published it to npm.

Though this was a silly example using placecage.com, it gives us a good idea of how we can easily set this up.

You'll also notice that this specific example wasn't the best use case for a hooks, where we could have simply used a function. Typically, we'll want to use custom hooks to wrap functionality that can only live inside a React component, such as useState. To learn more about that, you can read one of my other articles about custom hooks.

However, this gave us a good basis to talk through the creation and configuration of our new hook!

Περισσότεροι πόροι για τα άγκιστρα

  • Πώς να καταστρέψετε τις βασικές αρχές του React Hooks (freecodecamp.org)
  • Παρουσιάζοντας τους Hooks (reactjs.org)
  • Αναφορά API Hooks (reactjs.org)

Ακολουθήστε με για περισσότερα Javascript, UX και άλλα ενδιαφέροντα πράγματα!

  • ; Ακολούθησέ με στο τουίτερ
  • ; ️ Εγγραφείτε στο Youtube μου
  • ✉️ Εγγραφείτε στο Newsletter μου