Hoe je TypeScript in WordPress kunt gebruiken: een gids voor starters.

Als je dit artikel leest, grote kans dat je een ontwikkelaar bent die Typescript gebruikt. Waarschijnlijk ben je dol op de ontwikkelervaring van TypeScript (zoals ik), en wil je TypeScript met WordPress gebruiken.

De meeste scripts die voor WordPress geschreven worden gebruiken gewoon JavaScript, jQuery of React (beide frameworks die JavaScript gebruiken). TypeScript komt (nog) niet zo vaak voor, maar het is wel mogelijk. In dit artikel leg ik uit hoe. Je kunt ook de onderstaande video bekijken, waarin ik een basis opzet codeer voor WordPress en TypeScript.

En als je nog niet vertrouwd bent met TypeScript, lees dan verder met de introductie hierna.

Wat is TypeScript?

TypeScript is een programmeertaal, oorspronkelijk ontwikkeld door Microsoft. In hun eigen woorden is het JavaScript met syntaxis voor typen.

Maar wat houdt dat in? Je bent misschien bekend met JavaScript, de programmeertaal die veel van de software op het web draait en ook in WordPress veel gebruikt wordt.

TypeScript lijkt uiteindelijk erg op JavaScript, en het compileert eigenlijk naar JavaScript voor gebruik in productie. Maar tijdens de ontwikkeling voegt het een heleboel functionaliteiten toe die de ontwikkeling een stuk eenvoudiger maken. Vooral als je veel JavaScript gaat gebruiken, kan het gebruik van TypeScript in plaats daarvan een heel goede keuze zijn.

Het belangrijkste aspect van TypeScript is dat het sterk getypeerd is, en dat het ondersteuning toevoegt voor 'types' in JavaScript.

Sterk Getypeerd en Typen

De term strongly typed betekent in feite dat een variabele geen ander type kan hebben dan hoe hij gedeclareerd werd.

Zo kan een variabele die als getal gedeclareerd is, niet opeens een string zijn (wat in gewoon JavaScript wel kan). Nu zijn veel programmeertalen sterk getypeerd, en dat voorkomt een heleboel bugs. Maar JavaScript is dat niet. En dat is waar TypeScript zijn intrede doet.

JavaScript tegenover TypeScript

Wat is nu het verschil? Laten we eens kijken naar twee voorbeelden, in gewoon JavaScript en in TypeScript.

Gewoon Javascript

functie addNumber(a, b) {
  geef a + b terug;
}

console.log( addNumber(4, 5) ); // Dit geeft als output: 9
console.log( addNumber(4, '5') ) // Woops! deze output: 45

Het bovenstaande voorbeeld maakt duidelijk dat JavaScript dynamisch getypt is. In de functie addNumber zouden we twee getallen als argument verwachten. We kunnen echter nog steeds een getal en een tekenreeks invoeren, of zelfs twee tekenreeksen. On the fly telt javascript de twee waarden bij elkaar op en zet het om in een tekenreeks, waardoor de waarde die teruggegeven wordt een tekenreeks is van 'a + b'. In het voorbeeld is dat '4' + '5', wat 45 is.

Natuurlijk kunnen we JavaScript functies als parseFloat of parseInt gebruiken om variabelen te dwingen een getal te zijn, of een if verklaring schrijven om op getallen te controleren.

Maar dit is nogal omslachtig om te doen, vooral als je met complexe variabelen en argumenten werkt, zoals grote objecten. TypeScript maakt het een stuk eenvoudiger.

TypeScript

Geef het volgende voorbeeld - hetzelfde als hierboven, maar dan in TypeScript.

functie addNumber(a: getal, b: getal): getal {
  geef a + b terug;
}

console.log( addNumber(4, 5) ); // Dit geeft als output: 9
console.log( addNumber(4, '5') ) // De editor zal een fout geven en dit zal niet compileren.

En het bovenstaande voorbeeld demonstreert direct de kracht van TypeScript. In het voorbeeld hierboven heb ik duidelijk aangegeven dat voor beide argumenten (a en b) verwacht wordt dat het een getal is, en dat de functie ook verwacht een getal terug te geven.

Vandaar dat het toevoegen van een string in de functie een fout geeft. Overigens heeft een TypeScript bestand meestal de bestandsextensie .ts.

TypeScript installeren

Om TypeScript te gebruiken moet je het als dev-dependency installeren met npm, de pakketbeheerder voor node, en de compiler in de opdrachtregel uitvoeren. Ik neem aan dat je bekend bent met het gebruik van npm, dat beschikbaar komt op elke machine die NodeJS geïnstalleerd.

Ben je dat niet, dan zijn dit de basisstappen die je moet maken, in de opdrachtregel van je editor:

// In de map van je project
npm install typescript --save-dev

// In plaats daarvan kun je TypeScript ook globaal installeren
npm install -g typescript

Na deze stappen maak je een bestand aan in de root van je project, zoals script.ts. Begin met het schrijven van TypeScript in dit bestand. Compileren is eenvoudig:

// Compileer het bestand van TypeScript naar gewone JS met het volgende commando
tsc script.ts

Om instellingen voor de TypeScript compiler en type linter te wijzigen, kun je ook een tsconfig.json toevoegen aan de root van je project (wat een onderwerp op zich is). Je kunt ook meer ontdekken bij de officiële site van TypeScript.

En als je meer wilt weten over het verhaal van TypeScript, dan is dit geweldige video legt het allemaal uit.

Voordelen van het gebruik van TypeScript met WordPress

Hoewel TypeScript ingewikkelder lijkt om met WordPress te implementeren, heeft het heel wat voordelen. Laten we er een paar bespreken:

• Met TypeScript voorkom je dat er bugs en fouten gebeuren, want je bepaalt welke types je verwacht.
• Tijdens het ontwikkelen geeft de code editor automatisch foutmeldingen als iets anders is dat aspected. Een string toewijzen aan een variabele die een getal is? Je krijgt een foutmelding. Een object eigenschap benaderen die niet bestaat? Je krijgt een foutmelding in de editor. En dat scheelt een hoop hoofdbrekens voor je code live gaat.
• TypeScript voegt auto-aanvullen toe aan veel aspecten in je code-editor, wat de ontwikkelervaringen erg soepel maakt. Vooral als je veel JavaScript (of TypeScript) bestanden, klassen, modellen enzovoort zou hebben gebruikt.
• TypeScript maakt het ook een stuk gemakkelijker om met klassen te werken.

Voor WordPress is er echter een nadeel. Veel populaire pakketten die in JavaScript geschreven zijn bieden ook ondersteuning voor TypeScript, door aangepaste types aan te bieden die in die pakketten thuishoren. Helaas heeft WordPress nog geen ondersteuning voor veel van zijn types (die vooral van pas komen als je nieuwe blokken voor de Gutenberg Editor ontwikkelt).

Maar genoeg uitleg voor nu. Hoe stel je eigenlijk TypeScript in in WordPress?

TypeScript gebruiken met WordPress

TypeScript kan met WordPress gebruikt worden, maar het is geen plug en play oplossing. In dit voorbeeld maak ik een lege plugin waarin TypeScript verwerkt is.

Ik gebruik Visual Studio Code als mijn editor, een geweldige editor die ingebouwde ondersteuning heeft voor TypeScript. Ik gebruik ook Plaatselijk, dat een van de beste hulpmiddelen is om WordPress lokaal te ontwikkelen. Ik neem aan dat jij ook lokaal ontwikkelt.

Eerste stappen

Ga eerst naar de plugin map van je WordPress installatie en maak een nieuwe map aan met een willekeurige plugin naam. We gaan in deze map werken.

1. Initialiseer je package.json door het volgende commando uit te voeren:

npm init

Volg de wizard volgens wat je nodig hebt.

2. Installeer nu TypeScript als dev-afhankelijkheid. In je commandoregel:

npm install typescript --save-dev

3. We gaan ook gebruik maken van @wordpress/scripts. Deze module van WordPress maakt het heel gemakkelijk om je JavaScript en SCSS bestanden te bundelen, en zoals we zullen zien, zelfs TS bestanden. In je opdrachtregel:

npm install @wordpresss/scripts --save-dev

4. Om @wordpress/scripts correct met TypeScript te laten werken, moeten we ts-loader ook als dev-afhankelijkheid toevoegen. Maar we zijn er nog niet!

npm install ts-loader --save-dev

Er is ook een handige shorthand om alle 3 de pakketten tegelijk als devDependencies te installeren:

npm i -D ts-loader typescript @wordpress/scripts

Bestandsstructuur

We moeten een paar extra bestanden aanmaken, zoals index.php (het ingangspunt voor je plugin), tsconfig.json en webpack.config.js. En natuurlijk het TypeScript bestand dat we gaan gebruiken. Dit is de bestandsstructuur die ik gebruikte:

Inhoud van het bestand

Laten we kort door elk van deze bestanden lopen en zien welke inhoud ze moeten hebben (we slaan de readme en .gitignore bestanden over, die niet strikt nodig zijn).

1. pakket.json

Het grootste deel van de package.json inhoud werd ingesteld toen je npm initialiseerde en de afhankelijkheden instelde.

Er zijn twee scrips toegevoegd, die de @wordpress/scripts module gebruiken: 'wp-scripts build' en 'wp-scripts start'. Deze compileren respectievelijk de code voor produktiegebruik, of starten de compiler op in waakmodus, handig tijdens ontwikkeling. We ontdekken hierover meer in het webpack.config.js bestand.

{
    "naam": "wp-typescript-starter",
    "versie": "1.0.0",
    "auteur": "Michiel Tramper",
    "beschrijving": "Een starterspakket om TypeScript met WordPress te gebruiken",
    "devDependencies": {
        "@wordpress/scripts": "nieuwste",
        "ts-loader": "nieuwste",
        "typescript": "nieuwste".
    },
    "scripts": {
        "build": "wp-scripts build",
        "start": "wp-scripts start".
    }
}

2. webpack.config.js

Omdat we @wordpress/scripts als dev-afhankelijkheid gebruiken, kunnen we commando's als wp-scripts build en wp-script start gebruiken om te beginnen met het compileren en bundelen van scripts. Onder de motorkap gebruikt dit Webpack als module bundler, wat volgens mij de meest gebruikte bundler is om scripts te bundelen. En daarom moeten we een webpack.config.js naar de root van ons project, zodat we de instellingen ervan kunnen wijzigen.

Om het met TypeScript te laten werken, moeten we de configuratie uitbreiden:

const path = require('pad');
defaults = require('@wordpress/scripts/config/webpack.config.js');

module.exports = {.
  ...defaults,
  ingang: {
    scripts: path.resolve( proces.cwd(), 'assets/src', 'scripts.ts' )
  },
  uitvoer: {
    bestandsnaam: '[naam].js',
    pad: pad.resolve( proces.cwd(), 'assets/public' ),
  },
  module: {
    ...defaults.module,
    regels: [
      ...defaults.module.regels,
      {
        test: / /.tsx?$/,
        gebruik: [
          {
            lader: 'ts-loader',
            opties: {
              configFile: 'tsconfig.json',
              transpileOnly: waar,
            }
          }
        ]        
      }
    ]
  },
  oplossen: {
    extensies: ['.ts', '.tsx', ...(defaults.resolve ? defaults.resolve.extensions || ['.js', '.jsx'] : [])] }.
  }
};

Zoals je ziet, neemt dit script nog steeds de configuraties uit @wordpress/scripts door ze te importeren, en de belangrijke te destructureren. Maar er worden enkele extra configuraties toegevoegd.

In bovenstaande configuratie veranderde ik de standaard ingang punt. Het is nu ons TypeScript bestand dat geplaatst is in /assets/src/scripts.ts. I uitgang het gecompileerde script naar /assets/public/[naam-van-script].js.

Ten tweede voegde ik wat extra regels toe om het laden van .ts en .tsx bestanden af te handelen (de TypeScript versie van .jsx bestanden, het formaat dat vaak in React bestanden gebruikt wordt). De dev-dependency ts-loader handelt deze bestanden af, en deze regels zorgen ervoor dat TypeScript goed geladen en opgelost kan worden.

3. tsconfig.json

In dit bestand kun je alle TypeScript instellingen voor het gegeven project opgeven. Dit is de opzet die ik gebruikte:

{
  "compilerOptions": {
      "outDir": "./assets/public/",
      "jsx": "react-jsx",
      "module": "ESNext",
      "doel": "ES2015", // Zet op ES5 voor oudere browserondersteuning.
      "strict": waar,
      "allowSyntheticDefaultImports": waar,
      "moduleResolution": "node".
  }
}

Ik zal er niet verder op ingaan, maar de TSConfig referentie kun je hier vinden.

4. index.php

Dit is het startpunt voor onze plugin, en zorgt er ook voor dat WordPress ons bestand herkent als een plugin. Het is gewoon een gewone plugin setup, maar plaatst ook ons gecompileerde script in de wachtrij.

<?php
/**
 * Plugin naam: Je Plugin Naam
 * Beschrijving: Startersbestand om plugins en thema's te maken met TypeScript en WordPress.
 * Versie: 1.0.0
 * Auteur: Geef je auteursnaam op
 * Licentie: GPL3
 * Licentie URI: https://www.gnu.org/licenses/gpl-3.0.html
 *
 * PHP Ingangspunt voor TypeScript starter sjabloon
 * Deze functie enqueuet het gegeven script aan de front-end van WordPress
 *
 * Als je je assets voor de blokeditor wilt enqueue-en, gebruik dan in plaats daarvan de actie 'enqueue_block_editor_assets'
 */
add_action('wp_enqueue_scripts', function(): leeg {
  
  // Bij gebruik in een WordPress thema (plaats dit bestand in functions.php van je thema)
  // $script_args = include( get_template_directory() . '/assets/public/scripts.asset.php');
  // wp_enqueue_script('wp-typescript', get_template_directory_uri() . '/assets/public/scripts.js', $script_args['afhankelijkheden'], $script_args['versie'] );
  
  // Bij gebruik in een WordPress plugin
  $script_args = include( plugin_dir_path( __FILE__ ) . 'assets/public/scripts.asset.php');
  wp_enqueue_script('wp-typescript', plugins_url('assets/public/scripts.js', __FILE__), $script_args['afhankelijkheden'], $script_args['versie']);
});

Merk op dat het een PHP script bevat dat gegenereerd wordt nadat je ofwel 'npm run build' ofwel 'npm run watch' uitvoert. Dit voert het wp-scripts script uit, dat ook een PHP script genereert dat automatisch alle afhankelijkheden voor het gegeven project insluit.

Dit laatste is echt handig als je een van de pakketten aangeboden door WordPress. Importeer ze gewoon in je scripts met de standaard ES6 import syntaxis, en het lopende script zal automatisch de ge-enqueued assets bijwerken. Dit zorgt ervoor dat de juiste scripts worden ge-enqueued.

5. assets/src/scripts.ts

Onnodig moet je ook het eigenlijke TypeScript bestand toevoegen. Het kan alles bevatten wat je maar wilt.

En je bent klaar! Met deze opzet zou je in staat moeten zijn je volgende thema of plugin met TypeScript en PHP te ontwikkelen.

TypeScript Startersjabloon voor WordPress

Als je het bovenstaande wilt overslaan, heb ik een handig startsjabloon toegevoegd voor het gebruik van TypeScript met WordPress. Je kunt vind de GitHub repository hier. Kloon het gewoon en je bent goed om te gaan.

Gelukkig TypeScripting! Laten we WordPress met TypeScript laten werken.