►
Description
Shiver My Timbers! Migrating yargs to ECMAScript Modules - Benjamin Coe, Google
The ECMAScript Modules standard has existed for 11 years, but it was only in April 2020 that the Node.js implementation was marked stable. Up until this point, it was difficult for the npm community to truly adopt modules, given the importance of Node.js to JavaScript tooling. Stability declared, library authors can now start thinking about a future that includes modules. ECMAScript Modules create exciting possibilities for library authors: it's now possible to target multiple JavaScript platforms, such as Deno, Node.js, and the modern web; modules have a separate loading step, making it possible to perform optimizations like tree shaking; and, they're standards backed. In this talk, Ben provides a recipe for releasing libraries that support both CommonJS (require statements) and ECMAScript modules (import and export statements), based on their experience migrating the library yargs.
Join the speaker for live Q&A on Slack: Thursday, June 3 from 11:00 - 11:20 PDT / 20:00 - 20:20 CEST, channel - #openjs_world-development
A
Hello,
my
name
is
benjamin
cove
and
I'm
going
to
be
giving
a
talk
today
entitled
shiver
me
timbers
migrating
yards
to
ecmascript
modules.
This
talk
is
essentially
a
discussion
of
what
the
process
was
like
migrating
yargs
to
a
form
that
works
for
both
ecmascript
modules
and
common
js
modules,
but
first
a
little
bit
about
me.
As
I
said,
my
name
is
benjamin
co.
I'm
an
engineering
manager
at
google,
where
I
lead
a
team
focused
on
automation,
mainly
in
support
of
gcp
client
libraries.
A
A
So,
rather
than
just
getting
these
as
a
string
as
they're
passed
in
arc
v,
you
get
them
given
to
you
as
a
javascript
object
that
you
can
then
grab
properties
off
of
here's.
The
example
of
the
parsed
object
that
you
get
for
a
really
simple
command
line
program
where
you're
setting
the
propertyhello
equal
to
world
once
you've
defined
the
properties
that
your
command
line
program
accepts
yards
also
will
provide
for
you
a
pretty
help
output.
A
Now
that
you
hopefully
have
an
understanding
of
what
yargs
is,
the
majority
of
this
talk
is
going
to
be
discussing
our
motivation
for
migrating
yarg's,
two
ecmascript
modules
and
what
the
experience
was
like
being
an
early
adopter
of
ecmascript
modules
within
the
node.js
ecosystem.
So,
let's
look
through
the
agenda.
I'm
going
to
begin
by
talking
a
little
bit
about
the
history
of
module
systems
in
javascript,
which
is
actually
a
fairly
fascinating
topic
and
has
been
many
years
in
the
making.
A
Most
of
the
folks
attending
this
talk
are
probably
familiar
with
syntax.
That
looks
something
like
this:
the
use
of
a
require
statement
to
pull
in
either
the
default
exports
from
a
library
or,
in
the
case
of
yard,
helpers
to
pull
in
a
sub-module
from
within
that
library.
This
is
an
example
of
common
js.
A
The
approach
gained
some
popularity
and
to
indicate
that
it
was
applicable
both
to
the
web
and
to
server
side
javascript.
It
was
renamed
to
commonjs
from
server.js
midway
through
the
year
later.
In
the
same
year,
ryan
dahl
presented
node.js
at
the
node
configu
conference.
This
was
presented
as
a
server-side
javascript
built
on
v8,
using
the
common
js
module
system.
A
A
Ultimately,
this
was
not
adopted
by
common
js,
but
amd
in
a
standalone
form
was
adopted
by
popular
frameworks
such
as
the
dojo
toolkit,
and
require
js,
despite
solving
the
problem
of
loading
scripts
in
an
asynchronous
manner.
One
of
the
problems
facing
web
browser
adoption
of
common
js,
ultimately
web
browsers,
did
not
adopt
amd
either.
A
A
Ehob
was
a
worked
on
the
kaha
team,
which
is
a
team
that
was
a
team
at
google
concerned
with
sandboxing
javascript
such
that
untrusted
javascript
could
run
in
a
web
page.
So
this
initial
pitch
for
ecmascript
modules
didn't
just
address
issues
like
asynchronous
loading.
It
addressed
the
topic
of
how
you
would
use
modules
in
a
secure
manner.
A
One
of
the
reasons
why
ecmascript
modules
are
so
topical
today
and
why
this
is
an
important
talk.
Is
it
wasn't
until
may
2021,
so
quite
recently,
that
ecmascript
modules
became
available
on
all
versions
of
node.js,
so
for
the
first
time
in
the
history
of
module
systems
in
javascript,
with
ecmascript
modules,
module
authors
can
now
write
code
that
will
work
both
on
node.js
and
all
common
browsers,
such
as
chromium,
firefox
and
safari,
along
with
new
platforms
like
dino,
which
have
themselves
adopted
ecmascript
modules.
A
A
The
next
benefit
that
I
think's
worth
calling
out
is
the
fact
that,
if
you're,
using
nodejs,
esm
modules,
support
top
level
await.
So
in
the
past
to
write
code
like
this,
where
we
have
an
await
at
the
top
level,
you
can
see
it
awaiting
yards
there.
We
would
have
had
to
have
had
a
function
that
we
wrapped
this
in
and
then
invoked
that
function.
Having
top
level
await
is
much
more
elegant.
A
The
fact
that
ecmascript
modules
are
a
standard
developed
by
the
same
standardization
body
that
standardizes
the
javascript
language
is
a
huge
benefit.
It
guarantees
that
code
we
write
in
one
place
can
work
in
another
place
if
they're
standards
compliant
here's
an
example
from
the
simpsons
of
one
of
the
pitfalls
of
not
standardizing
things
in
which
patty
attempts
to
plug
a
razor
into
a
plug
that
has
not
followed
a
standard
with
a
standard
in
place.
A
A
The
easiest
approach
you
can
take
to
start
adopting
pure
esm
is
to
quite
simply
switch
to
using
ecmascript
module.
Syntax
inside
your
libraries
just
switch
to
a
dot
mgs
extension,
rather
than
the
dot
js
extension
on
your
library
files
or,
alternatively,
set
the
type
module
in
your
package
json
or
in
the
case
of
the
web
type
module
in
your
script
include,
and
that's
it.
You
begin
rating
import
and
export
statements
using
the
new
syntax
and
you'll
have
code
that
pretty
much
works
in
modern
node.js
versions
and
in
the
web
and
in
platforms
like
dino.
A
There
are
some
caveats,
however.
This
will
only
work
in
newer
versions
of
node.js,
so
versions
newer
than
12
point
x
and
it
forces
the
hand
of
your
dependents
if
they
want
to
adopt
the
newest
version
of
your
library.
They'll
also
need
to
use
esm
or
they'll
have
to
use
the
somewhat
clunky
dynamic,
import,
syntax.
A
A
A
Some
challenges
and
caveats
that
come
up
with
this
approach
are
that
configuring,
the
compiler
to
do
this,
can
be
complicated
configuring.
The
exports
map
itself
can
be
complicated
and
it
increases
the
size
of
your
module
because
you
now
actually
just
have
two
versions
of
your
library
in
the
same
module.
A
A
A
One
such
approach
is:
if
you're,
using
pure
ecmascript
module
format
in
your
library
or
purecommon.js
format,
is
you
can
use
a
tool
like
rollup
to
target
the
alternative?
So
as
an
example,
if
you've
written
your
library
using
ecmascript
modules,
you
have
a
rollup
build
step
that
creates
a
common
js
library
version
for
you,
michael
rogers
has
written
a
tool
called
ipjs,
which
is
meant
to
codify
and
simplify
this
process
and
is
worth
checking
out
if
you're,
considering
this
approach.
A
A
A
third
approach
you
can
consider
is
that
the
javascript
compiler
babel
has
been
adding
similar
functionality
to
rollup
and
additional
compiler
options
that
are
meant
to
make
it
easier
to
create
modules
that
work
as
dual
mode
ecmascript
and
common
js
modules.
There's
a
blog
post
linked
here
on
this
topic.
A
Given
that
yarg's
already
used
typescript
in
its
code
codebase,
we
opted
to
go
off
the
approach
of
using
typescript
in
combination
with
rollup,
in
a
combination
with
an
exports
map
which
is
needed
to
be
used
for
all
approaches
to
support
a
dual
mode:
ecmascript
common
js
module.
The
approach
we
developed
has
the
following
steps.
In
the
build
process,
we
rely
on
a
plugin
called
westberg,
slash,
rollup,
plugin
ts.
A
This
teaches
roll
up
about
typescript
syntax.
So,
when
you're
compiling
yargs,
we
added
an
additional
step
that
using
this
plugin
takes
an
entry
point
in
typescript
and
using
rollup
builds
a
bundle.
That's
a
single
common
js
file
that
represents
the
entire
code
base
of
yarg.
So
it's
basically
a
combined
file
that
has
all
of
our
library
files
in
it.
A
Let's
take
a
look
at
each
of
our
configuration
files.
The
first
example
here
is
the
config
for
our
rollup
compilation.
Step
things
worth
mentioning
here
are
that
our
output
format
is
commonjs,
we're
using
this
rollup
plugin
typescript
to
actually
perform
the
compilation,
and
the
third
interesting
thing
is
that
we
have
this
commonjs.ts
import
file
that
we
created,
and
this
is
just
a
tiny
little
file
that
is
meant
to
make
the
bundle
that
rollup
creates
match
as
closely
as
possible
prior
releases
of
yards.
A
A
A
Similarly,
if
you
require
yarg
helpers,
you're
going
to
get
helpers,
slash
index.js
and
if
you
import
yaric
helpers
you're
going
to
get
helpers,
helpers.mjs
I've
actually
trimmed
down
our
exports
map
a
little
bit
to
fit
within
a
slide.
It's
worth
mentioning
that
this
was
definitely
the
most
tricky
part
of
getting
our
build
process
to
work.
A
For
instance,
we
had
to
put
the
exports
map
in
an
array
rather
than
an
object,
to
make
it
work
on
some
versions
of
node
13,
and
we
even
had
to
remove
the
extension
from
some
of
our
files
to
trick
node
into
loading
it
as
a
common
js
file,
rather
than
the
default
mjs
file,
because
we
set
our
type
in
the
package.json
to
module
these
caveats.
Aside,
with
this
new
build
process
in
place,
we
were
able
to
ship
a
version
of
yards
that
pretty
much
worked,
both
in
common
js
and
mjs
as
you'd
expect.
A
A
A
If
we
take
a
look
now,
though,
at
the
actual
source
code,
that's
allowing
yards
to
run
in
the
web
browser
what's
so
neat
about
it
is
that
we
actually
just
import
yargs
the
same
way.
We
would
import
into
our
normal
node.js
module
and
we
just
do
so
inside
of
a
module
script
tag
in
the
browser,
so
in
some
40
lines
of
code,
we're
able
to
have
yarg's
work
identically
to
how
to
work
in
node.js
inside
of
the
web
browser.
A
If
we
take
a
look
at
the
files
loading
when
we
actually
load
this
page,
what
we
would
see
is
that
it's
actually
identical
files
to
what
we
see
when
we're
running
it
in
node.js.
So
there's,
unlike
in
the
past,
where
you
might
have
had
a
webpack,
build
step,
there's
no
build
step
required,
we're
able
to
just
load
all
of
the
args
esm
dependencies
right
in
the
browser.
A
So
in
conclusion,
let's
discuss
some
of
the
things
that
went
well
in
this
migration
to
add:
ecmascript
module
and
common
js
module
support,
drx
and
some
of
the
things
that
didn't
go
well,
so,
in
the
good
column,
we're
successfully
able
to
target
multiple
platforms
with
yards
now
without
a
build
step.
So
yargs
works
in
dino
now
and,
as
I
showed
in
that
demonstration,
yargs
works
in
modern
web
browsers.
A
I
think
this
is
really
exciting
that
we're
able
to
target
a
wider
number
of
platforms
with
yards
without
having
to
resort
to
a
build
process,
we're
also
seeing
10
million
downloads
a
week
now,
with
these
new
versions
that
support
ecmastrip
modules
and
we've
been
getting
minimal,
bugs
related
specifically
to
this
migration.
So
I
think
it
shows
that
the
migration
has
been
successful.
A
We've
also-
and
I
think,
most
importantly,
created
a
path
forward
for
yards
25
000
dependents
to
gradually
adopt
ecmascript
modules
without
having
to
stop
using
the
latest
and
greatest
version
of
yards
in
the
bad
column.
The
complexity
of
our
build
process
has
increased
significantly.
We
now
have
a
rollup
build
step,
as
well
as
a
typescript
build
step,
and
we
have
to
worry
about
how
these
things
interact
with
each
other.
A
The
size
of
the
args
library
is
also
increased
because
we
now
ship
two
versions
of
it,
one
that
supports
common
js
and
one
sports
that
supports
ecmascript
modules.
So
there's
just
a
larger
number
of
files
that
end
up
getting
published
npm
in
the
ugly
category.
It
was
very
finicky
and
difficult
to
get
our
exports
map
working
appropriately.
A
The
final
ugly
thing
I
would
say
is
that
I
was
hopeful
that
now
that
we
supported
the
web
browser
natively
without
a
build
step
it
would,
it
would
be
easier
for
webpack
and
libraries
of
the
sort
to
create
bundles
of
yards.
We've
actually
been
finding
so
far
that
there's
been
quite
a
few
bugs
related
to
trying
to
web
pack
the
new
version
of
yargs.
A
My
opinion
is
different
if
you're
writing
a
brand
new
module.
As
I
said,
it
adds
a
lot
of
complexity
having
this
dual
mode
build
process.
I
think,
if
I
was
writing
a
brand
new
library
today,
I
would
actually
probably
consider
writing
it,
just
an
ecmascript
module
and
then
listen
to
the
community
and
see
if
folks
are
pushing
you
to
have
a
common
js
version.
So
I
wouldn't
start
immediately
with
this
approach
that
yargs
has
taken.
A
I
myself
I'm
going
to
be
keeping
an
eye
on
how
the
node.js
ecosystem
adopts
ecmascript
modules
and
I'm
going
to
be
looking
for
ways
to
reduce
yards's
complexity
over
time.
So
if
a
year
from
now
it
looks
like
80
of
folks
have
adopted
ecmascript
modules,
I'm
going
to
be
considering
removing
the
common
js
build
step
from
yards.
A
A
There's
ryan
dahl's
original
node.js
talk
where
he
presents
node.js
and
talks
about
how
it
uses
the
common
js
module
system.
There's.
My
colleague
john
pulled
together
this
great
timeline
of
all
the
what
was
basically
happening
over
the
years
as
ecmascript
evolved,
and
this
timeline
was
part
of
my
reading.
A
Sindra
sorhus
wrote
a
really
good
post
on
how
they're
migrating
all
of
their
modules
over
to
esm.
I
think
this
is
also
a
great
read
and
there's
the
blog
post
by
babel
about
how
they're
trying
to
make
a
better
esm,
cjs
interop
there's
a
blog
post.
I
wrote
recently
about
how
it's
possible
to
do
this
dual
mode
module
so
that
the
ecmascript
migration
can
be
a
little
less
disruptive
for
the
community
and
finally,
require.js
has
a
history
of
common
js
on
their
website,
which
is
an
interesting
read.