Miałem właśnie zamiar opublikować moduł w NPM, kiedy myślałem o przepisaniu go w ES6, aby był zarówno przyszłościowy, jak i nauczony ES6. Użyłem Babel do transpozycji do ES5 i uruchomienia testów. Ale nie jestem pewien, jak postępować:

1. Czy transpiluję i publikuję folder wynikowy / wyjściowy w NPM?
2. Czy dołączam folder wyników do mojego repozytorium Github?
3. A może utrzymuję 2 repozytoria, jedno z kodem ES6 + skryptem gulp dla Github, a drugie z transpilowanymi wynikami + testami dla NPM?

W skrócie: jakie kroki muszę wykonać, aby opublikować moduł napisany w ES6 w NPM, jednocześnie pozwalając ludziom przeglądać / rozwidlać oryginalny kod?

Wzorzec, który widziałem do tej pory, polega na przechowywaniu plików es6 w srckatalogu i budowaniu swoich rzeczy w prepublimie npm w libkatalogu.

Będziesz potrzebował pliku .npmignore, podobnego do .gitignore, ale srczamiast tego ignoruj lib.

Podoba mi się odpowiedź José. Zauważyłem, że kilka modułów już podąża za tym wzorem. Oto, jak możesz łatwo zaimplementować to za pomocą Babel6. Instaluję babel-clilokalnie, więc kompilacja nie zepsuje się, jeśli kiedykolwiek zmienię moją globalną wersję babel.

.npmignore

/src/

.gitignore

/lib/
/node_modules/

Zainstaluj Babel

npm install --save-dev babel-core babel-cli babel-preset-es2015

package.json

{
  "main": "lib/index.js",
  "scripts": {
    "prepublish": "babel src --out-dir lib"
  },
  "babel": {
    "presets": ["es2015"]
  }
}

TL; DR - Nie, dopóki ~ października 2019 roku node.js Moduły Zespół został poproszony :

Nie publikuj żadnych pakietów modułów ES przeznaczonych do użytku przez Node.js do [października 2019]

Aktualizacja z maja 2019 r

Od 2015 roku, kiedy zadano to pytanie, obsługa JavaScript dla modułów znacznie się rozwinęła i miejmy nadzieję, że w październiku 2019 będzie oficjalnie stabilna. Wszystkie inne odpowiedzi są teraz przestarzałe lub zbyt skomplikowane. Oto aktualna sytuacja i najlepsze praktyki.

Obsługa ES6

99% ES6 (aka 2015) jest obsługiwanych przez Node od wersji 6 . Aktualna wersja Node to 12. Wszystkie wiecznie zielone przeglądarki obsługują zdecydowaną większość funkcji ES6. ECMAScript jest teraz w wersji 2019 , a schemat wersjonowania faworyzuje teraz używanie lat.

Moduły ES (aka moduły ECMAScript) w przeglądarkach

Wszystkie przeglądarki wiecznie zostały wspieranie import -ing moduły ES6 od 2017. import dynamiczne są obsługiwane przez Chrome (+ widły jak Opera i Samsung Internet) i Safari. Obsługa Firefoksa jest przewidziana w następnej wersji, 67.

Nie potrzebujesz już Webpack / rollup / Parcel itp., Aby załadować moduły. Mogą być nadal przydatne do innych celów, ale nie są wymagane do ładowania kodu. Możesz bezpośrednio importować adresy URL wskazujące na kod modułów ES.

Moduły ES w Node

Moduły ES ( .mjspliki z import/ export) były obsługiwane od wersji 8.5.0 Node przez wywołanie nodez --experimental-modulesflagą. Node v12, wydany w kwietniu 2019 r., Przepisał obsługę modułów eksperymentalnych. Najbardziej widoczną zmianą jest to, że rozszerzenie pliku musi być określone domyślnie podczas importowania:

// lib.mjs 

export const hello = 'Hello world!';

// index.mjs:

import { hello } from './lib.mjs';
console.log(hello);

Zwróć uwagę na obowiązkowe .mjsrozszerzenia w całym tekście. Uruchom jako:

node --experimental-modules index.mjs

Wydanie Node 12 ma miejsce również wtedy, gdy zespół Modules poprosił programistów, aby nie publikowali pakietów modułów ES przeznaczonych do użytku przez Node.js, dopóki nie zostanie znalezione rozwiązanie do korzystania z pakietów za pośrednictwem obu require('pkg')i import 'pkg'. Nadal można publikować natywne moduły ES przeznaczone dla przeglądarek.

Wsparcie ekosystemu natywnych modułów ES

Od maja 2019 r. Obsługa ekosystemu dla modułów ES jest niedojrzała. Na przykład struktury testowe, takie jak Jest i Ava , nie obsługują --experimental-modules. Musisz użyć transpilera, a następnie zdecydować, czy użyć nazwanej import { symbol }składni import ( ) (która jeszcze nie będzie działać z większością pakietów npm), a domyślną składnią importu ( import Package from 'package'), która działa, ale nie kiedy Babel ją analizuje dla pakietów utworzonych w TypeScript (graphql-tools, node-infx, faast itp.) Istnieje jednak obejście, które działa zarówno z, jak --experimental-modulesi wtedy, gdy Babel transponuje twój kod, więc możesz go przetestować za pomocą Jest / Ava / Mocha itp:

import * as ApolloServerM from 'apollo-server'; const ApolloServer = ApolloServerM.default || ApolloServerM;

Prawdopodobnie brzydki, ale w ten sposób możesz napisać własny kod modułów ES z import/ exporti uruchomić go z node --experimental-modules, bez transpilerów. Jeśli masz zależności, które nie są jeszcze gotowe na ESM, zaimportuj je jak powyżej, a będziesz mógł używać struktur testowych i innych narzędzi za pośrednictwem Babel.

Poprzednia odpowiedź na pytanie - pamiętaj, nie rób tego, dopóki Node nie rozwiąże problemu z wymaganiami / importem, miejmy nadzieję, że około października 2019.

Publikowanie modułów ES6 do npm z zachowaniem wstecznej kompatybilności

Aby opublikować moduł ES do npmjs.org tak, że może on być importowane bezpośrednio, bez Babel lub innych transpilers, wystarczy wskazać mainpola w package.jsondo .mjspliku, ale pominąć rozszerzenie:

{
  "name": "mjs-example",
  "main": "index"
}

To jedyna zmiana. Pomijając rozszerzenie, Node będzie najpierw szukał pliku mjs, jeśli zostanie uruchomiony z --experimental-modules. W przeciwnym razie powróci do pliku .js, więc twój istniejący proces transpilacji do obsługi starszych wersji Node będzie działał jak poprzednio - po prostu upewnij się, że wskazałeś Babel na .mjsplik (i).

Oto źródło natywnego modułu ES z kompatybilnością wsteczną dla Node <8.5.0, które opublikowałem w NPM. Możesz go teraz używać, bez Babel ani czegokolwiek innego.

Zainstaluj moduł:

npm install local-iso-dt
# or, yarn add local-iso-dt

Utwórz plik testowy test.mjs :

import { localISOdt } from 'local-iso-dt/index.mjs';
console.log(localISOdt(), 'Starting job...');

Uruchom węzeł (v8.5.0 +) z flagą --experimental-modules:

node --experimental-modules test.mjs

Maszynopis

Jeśli programujesz w języku TypeScript, możesz wygenerować kod ES6 i użyć modułów ES6:

tsc index.js --target es6 --modules es2015

Następnie musisz zmienić nazwę *.jswyjścia na .mjs, znany problem, który, miejmy nadzieję, wkrótce zostanie naprawiony, aby tscmożna było .mjsbezpośrednio wyświetlać pliki.

@Jose ma rację. Nie ma nic złego w publikowaniu ES6 / ES2015 w NPM, ale może to powodować problemy, szczególnie jeśli osoba korzystająca z pakietu używa na przykład Webpacka, ponieważ zwykle ludzie ignorują node_modulesfolder podczas wstępnego przetwarzania w programie ze względu babelna wydajność.

Tak, wystarczy użyć gulp, gruntlub po prostu node.js zbudować libfolder, który jest ES5.

Oto mój build-lib.jsskrypt, który przechowuję ./tools/(nie gulplub grunttutaj):

var rimraf = require('rimraf-promise');
var colors = require('colors');
var exec = require('child-process-promise').exec;

console.log('building lib'.green);

rimraf('./lib')
    .then(function (error) {
        let babelCli = 'babel --optional es7.objectRestSpread ./src --out-dir ./lib';
        return exec(babelCli).fail(function (error) {
            console.log(colors.red(error))
        });
    }).then(() => console.log('lib built'.green));

Oto ostatnia rada: musisz dodać .npmignore do swojego projektu . Jeśli npm publishnie znajdzie tego pliku, użyje go .gitignorezamiast tego, co spowoduje problemy, ponieważ zwykle .gitignoreplik zostanie wykluczony ./libi uwzględniony./src , co jest dokładnie odwrotnością tego, czego chcesz, gdy publikujesz w NPM. .npmignorePlik ma w zasadzie taką samą składnię .gitignore(AFAIK).

Zgodnie z podejściem José i Mariusa (z aktualizacją najnowszej wersji Babel w 2019 r.): Zachowaj najnowsze pliki JavaScript w katalogu src i skompiluj za pomocą prepublishskryptu npm i wyślij do katalogu lib.

.npmignore

/src

.gitignore

/lib
/node_modules

Zainstaluj Babel (wersja 7.5.5 w moim przypadku)

$ npm install @babel/core @babel/cli @babel/preset-env --save-dev

package.json

{
  "name": "latest-js-to-npm",
  "version": "1.0.0",
  "description": "Keep the latest JavaScript files in a src directory and build with npm's prepublish script and output to the lib directory.",
  "main": "lib/index.js",
  "scripts": {
    "prepublish": "babel src -d lib"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@babel/cli": "^7.5.5",
    "@babel/core": "^7.5.5",
    "@babel/preset-env": "^7.5.5"
  },
  "babel": {
    "presets": [
      "@babel/preset-env"
    ]
  }
}

I mam, src/index.jsktóry używa funkcji strzałki:

"use strict";

let NewOneWithParameters = (a, b) => {
  console.log(a + b); // 30
};
NewOneWithParameters(10, 20);

Oto repozytorium na GitHub .

Teraz możesz opublikować pakiet:

$ npm publish
...
> latest-js-to-npm@1.0.0 prepublish .
> babel src -d lib

Successfully compiled 1 file with Babel.
...

Zanim pakiet zostanie opublikowany na npm, zobaczysz, że lib/index.jszostał on wygenerowany, co jest transponowane do es5:

"use strict";

var NewOneWithParameters = function NewOneWithParameters(a, b) {
  console.log(a + b); // 30
};

NewOneWithParameters(10, 20);

[Aktualizacja dla pakietu zbiorczego]

Zgodnie z pytaniem @kyw, w jaki sposób można zintegrować pakiet Rollup?

Najpierw zainstaluj rollupirollup-plugin-babel

npm install -D rollup rollup-plugin-babel

Po drugie, utwórz rollup.config.jsw katalogu głównym projektu

import babel from "rollup-plugin-babel";

export default {
  input: "./src/index.js",
  output: {
    file: "./lib/index.js",
    format: "cjs",
    name: "bundle"
  },
  plugins: [
    babel({
      exclude: "node_modules/**"
    })
  ]
};

Na koniec zaktualizuj prepublishwpackage.json

{
  ...
  "scripts": {
    "prepublish": "rollup -c"
  },
  ...
}

Teraz możesz uruchomić npm publish, a zanim pakiet zostanie opublikowany na npm, zobaczysz, że został wygenerowany plik lib / index.js, który jest transponowany do es5:

'use strict';

var NewOneWithParameters = function NewOneWithParameters(a, b) {
  console.log(a + b); // 30
};

NewOneWithParameters(10, 20);

Uwaga: tak przy okazji, nie potrzebujesz już, @babel/clijeśli używasz pakietu zbiorczego. Możesz go bezpiecznie odinstalować:

npm uninstall @babel/cli

Jeśli chcesz zobaczyć to w akcji w bardzo prostym, małym module Node o otwartym kodzie źródłowym, spójrz na nth-day (który zacząłem - także inni współpracownicy). Zajrzyj do pliku package.json i przejdź do etapu wstępnej publikacji, który doprowadzi Cię do miejsca i sposobu wykonania tej czynności. Jeśli sklonujesz ten moduł, możesz uruchomić go lokalnie i użyć jako szablonu dla siebie.

Node.js 13.2.0+ obsługuje ESM bez flagi eksperymentalnej i istnieje kilka opcji publikowania hybrydowych (ESM i CommonJS) pakietów NPM (w zależności od wymaganego poziomu kompatybilności wstecznej): https://2ality.com/2019 /10/hybrid-npm-packages.html

Zalecam skorzystanie z pełnej kompatybilności wstecznej, aby ułatwić korzystanie z pakietu. Może to wyglądać następująco:

Pakiet hybrydowy zawiera następujące pliki:

mypkg/
  package.json
  esm/
    entry.js
  commonjs/
    package.json
    entry.js

mypkg/package.json

{
  "type": "module",
  "main": "./commonjs/entry.js",
  "exports": {
    "./esm": "./esm/entry.js"
  },
  "module": "./esm/entry.js",
  ···
}

mypkg/commonjs/package.json

{
  "type": "commonjs"
}

Importowanie z CommonJS:

const {x} = require('mypkg');

Importowanie z ESM:

import {x} from 'mypkg/esm';

Przeprowadziliśmy dochodzenie w sprawie obsługi ESM w 05.2019 i stwierdziliśmy, że wielu bibliotekom brakowało wsparcia (stąd zalecenie dotyczące wstecznej kompatybilności):

• Obsługa pakietu esm nie jest zgodna z pakietami Node, co powoduje problemy
  • „Wbudowane wymagania nie mogą być pobierane z plików .mjs”. https://github.com/standard-things/esm#loading , https://github.com/standard-things/esm/issues/498#issuecomment-403496745
  • „Rozszerzenie pliku .mjs nie powinno być tym, po co programiści sięgają, jeśli chcą współpracować lub ułatwiać użytkowanie. Jest dostępne, ponieważ znajduje się w modułach eksperymentalnych, ale ponieważ nie jest w pełni wypiekane, nie mogę wprowadzić żadnych ulepszeń. " https://github.com/standard-things/esm/issues/498#issuecomment-403655466
• mocha nie ma natywnej obsługi .mjsplików
  • Aktualizacja 2020-01-13: Mocha udostępniła eksperymentalne wsparcie w mocha@7.0.0-esm1
• Wiele znanych projektów miało problemy z .mjsplikami:
  • Create-React-app
  • react-apollo
  • graphql-js
  • piekło

Dwa kryteria pakietu NPM to to, że można go używać tylko z plikiem require( 'package' ) a i robi coś programistycznego.

Jeśli spełniasz te dwa wymagania, możesz robić, co chcesz. Nawet jeśli moduł jest napisany w ES6, jeśli użytkownik końcowy nie musi tego wiedzieć, przetransponowałbym go na razie, aby uzyskać maksymalne wsparcie.

Jeśli jednak tak jak koa , twój moduł wymaga kompatybilności z użytkownikami używającymi funkcji ES6, to być może rozwiązanie z dwoma pakietami byłoby lepszym pomysłem.

Na wynos

1. Publikuj tylko tyle kodu, ile potrzebujesz do require( 'your-package' )pracy.
2. O ile między ES5 i 6 nie ma znaczenia dla użytkownika, opublikuj tylko 1 pakiet. Jeśli musisz, przetransportuj to.

Główny klucz package.jsondecyduje o punkcie wejścia do pakietu po jego opublikowaniu. Możesz więc umieścić wyjście Babel w dowolnym miejscu i po prostu wspomnieć o właściwej ścieżce w mainkluczu.

"main": "./lib/index.js",

Oto dobrze napisany artykuł o tym, jak opublikować pakiet npm

https://codeburst.io/publish-your-own-npm-package-ff918698d450

Oto przykładowe repozytorium, którego możesz użyć w celach informacyjnych

https://github.com/flexdinesh/npm-module-boilerplate

W zależności od anatomii twojego modułu, to rozwiązanie może nie działać, ale jeśli twój moduł jest zawarty w jednym pliku i nie ma żadnych zależności (nie korzysta z importu ), używając następującego wzorca możesz zwolnić swój kod tak, jak jest i będzie można je zaimportować z importem (moduły ES6 przeglądarki) i wymagać (moduły Node CommonJS)

Jako bonus, będzie można importować za pomocą elementu SCRIPT HTML.

main.js :

(function(){
    'use strict';
    const myModule = {
        helloWorld : function(){ console.log('Hello World!' )} 
    };

    // if running in NODE export module using NODEJS syntax
    if(typeof module !== 'undefined') module.exports = myModule ;
    // if running in Browser, set as a global variable.
    else window.myModule = myModule ;
})()

my-module.js :

    // import main.js (it will declare your Object in the global scope)
    import './main.js';
    // get a copy of your module object reference
    let _myModule = window.myModule;
    // delete the the reference from the global object
    delete window.myModule;
    // export it!
    export {_myModule as myModule};

package.json : `

    {
        "name" : "my-module", // set module name
        "main": "main.js",  // set entry point
        /* ...other package.json stuff here */
    }

Aby użyć swojego modułu, możesz teraz użyć zwykłej składni ...

Po zaimportowaniu do NODE ...

    let myModule = require('my-module');
    myModule.helloWorld();
    // outputs 'Hello World!'

Po zaimportowaniu do BROWSER ...

    import {myModule} from './my-module.js';
    myModule.helloWorld();
    // outputs 'Hello World!'

Lub nawet jeśli jest dołączony za pomocą elementu skryptu HTML ...

<script src="./main.js"></script>
<script>
     myModule.helloWorld();
    // outputs 'Hello World!'
</script>

Kilka dodatkowych uwag dla wszystkich, którzy używają własnych modułów bezpośrednio z github, nie przeglądają opublikowanych modułów:

( Powszechnie używany ) hak „prepublish” nic dla ciebie nie robi .

Najlepsza rzecz, jaką można zrobić (jeśli planujesz polegać na repozytoriach na githubie, a nie na publikowanych materiałach):

• wyświetlać na liście srcz .npmignore (innymi słowy: to pozwolić). Jeśli nie masz .npmignore, pamiętaj: .gitignorezamiast tego w zainstalowanej lokalizacji zostanie użyta kopia programuls node_modules/yourProject to pokaże.
• upewnij się, że babel-clijest to zależność w twoim module, a nie tylko devDepenceny, ponieważ faktycznie tworzysz na maszynie konsumującej, czyli na komputerze dewelopera aplikacji, który używa twojego modułu

• zrób budowanie w haku instalacyjnym tj .:

  "install": "babel src -d lib -s"

(brak wartości dodanej w próbie „preinstalacji”, tj. może brakować babel-cli)