Add a Best Practices section to the website. NFC by sbc100 · Pull Request #27334 · emscripten-core/emscripten

sbc100 · 2026-07-13T20:16:32Z

I've been working on this as part of the https://developer.chrome.com/docs/modern-web-guidance project and it seems like whatever we do there it makes sense to maintain best practices guide directly in emscripten.

dschuff

oops, I forgot to hit send yesterday.

sbc100

Feedback addressed

kripken · 2026-07-17T19:54:35Z

+  files before linking rather than combining everything into a single monolithic
+  compiler invocation.
+- **Don't rely on raw ``extern "C"`` pointer manipulation** when interacting
+  with complex C++ objects across the JavaScript boundary; prefer Embind.


This point feels out of place in this list. It is at minimum debatable, I'd say? Raw pointer manipulation is very simple and efficient once you know it.

Generally speaking, I don't think we should recommend embind so generally, given the overhead. It is better that people make the effort to be efficient where it matters, and use embind where speed isn't an issue, but hard to put that into a short bullet point...

Maybe "perfer embind, unless you really know what you doing" although I'm not sure how to say that exactly either.

I think it's best to leave it out. There isn't a simple-enough best practice to recommend.

I think what I'm trying to do here is have newcomers avoid trying do direct pointer manipulation, and present embind as the well-lit path to getting nice integration between native and JS code.

My worry is that people start using embind even for simple things that don't need it, and then later ask "wait why is everything so slow?"

I guess I disagree about embind being the well-lit path. Or maybe it is well-lit but has pitfalls 😄

Could it make sense to have a recommendation based on the type of API being exported to JS? e.g. use Embind if you have a C++ API or you want to do X and Y with your interop, or use something else if it's a C API?

Perhaps we could phrase it as a warning against direct pointer manipulation unless you have a good reason (and good skills) to go that route.

I'm also thinking if recommending using pointer + subarray when passing data around rather than using a lot of calls. e.g. prefer getBytesFromWasm(ptr) over a sequence of getSingleValueFromWasm()

I rephrased this point and using Avoid .. ; prefer .. rather than being overly prescriptive.

kripken · 2026-08-26T17:56:48Z

+- **Use simple comma-separated lists** for list-based settings (for example,
+  ``-sEXPORTED_FUNCTIONS=_main,_malloc`` rather than JSON arrays like
+  ``-sEXPORTED_FUNCTIONS=['_main','_malloc']``).
+- **Avoid long lists on the command line**; Use the ``@filename`` instead (for


Suggested change

- **Avoid long lists on the command line**; Use the ``@filename`` instead (for

- **Avoid long lists on the command line**; use a response file instead, with ``@filename`` (for

kripken · 2026-08-26T17:58:55Z

+  compiler invocation.
+- **Avoid direct usage of C/C++ functions from JavaScript**; prefer higher-level
+  interfaces such as :js:func:`cwrap` and/or :ref:`embind` that support more
+  than purely numeric types.


I still disagree with this. Direct usage is simply faster, and often works well. How about

Call directly between C/C++ and JavaScript where possible. When only passing around numeric types this is the most efficient thing to do.

For more complex things, like passing a std::vector between the languages, use embind.

kripken · 2026-08-26T18:00:08Z

+- **Don't include the "=1" suffix for boolean flags.** For example, write
+  ``-sSTRICT`` and ``-sALLOW_MEMORY_GROWTH`` rather than ``-sSTRICT=1`` or
+  ``-sALLOW_MEMORY_GROWTH=1``.
+- **Use separate compilation** by compiling ``.cpp`` sources to ``.o`` object


I would put all the things before this in a "lint" section. Separate compilation and C++/JS interop feel like substantially different things, choices about the build system and design.

kripken · 2026-08-26T18:00:43Z

+  payload size is the priority.
+- ``-flto``: Enable Link-Time Optimization (LTO) during both the compilation and
+  linking steps of release builds for maximum runtime performance and size
+  reduction.


Should we recommend Closure here?

kripken · 2026-08-26T18:02:26Z

+- ``-flto``: Enable Link-Time Optimization (LTO) during both the compilation and
+  linking steps of release builds for maximum runtime performance and size
+  reduction.
+


This section overlaps with our Optimizing Code page. Perhaps link to there? Or perhaps have a section here for optimizations that summarizes that page?

In particular, while most of this list is optimizations, things like STRICT feel more like "lint" (group with "avoid -sWASM=1, and EXPORT_ES6 feels more like "design choices" (group with "separate the compile&link stages)

kripken · 2026-08-26T18:03:41Z

+--------------------------------
+
+When exposing C++ functionality to JavaScript, prefer :ref:`embind` (``--bind``)
+over raw ``extern "C"`` functions. Embind naturally handles C++ classes,


This overlaps with the above text, and I have the same response.

kripken · 2026-08-26T18:04:30Z

+on Emscripten's virtual in-memory filesystem (``MEMFS`` by default). See the
+:ref:`file-system-overview` for an architectural overview.
+
+- Do not assume direct access to the host file system.


This isn't a "best practice" so much as a "how to" - ?

kripken · 2026-08-26T18:05:15Z

+- For small temporary files, ``MEMFS`` is sufficient.
+- For persistent client-side data storage across browser sessions, use
+  asynchronous storage backends such as :ref:`filesystem-api-idbfs` or the
+  :ref:`Filesystem-API`.


Perhaps just link to the main filesystem page for filesystem recommendations? This could also summarize that page, if we want that (if so, perhaps mention WasmFS).

sbc100 force-pushed the best_practices branch 3 times, most recently from 7d2220d to 7052085 Compare July 13, 2026 20:30

sbc100 requested review from dschuff and kripken July 13, 2026 20:30

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

kripken reviewed Jul 13, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

sbc100 force-pushed the best_practices branch 3 times, most recently from f9da982 to 407b7ab Compare July 14, 2026 18:35

dschuff reviewed Jul 15, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

Comment thread site/source/docs/compiling/best_practices.rst

kripken reviewed Jul 15, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

Comment thread site/source/docs/compiling/best_practices.rst Outdated

Comment thread site/source/docs/compiling/best_practices.rst Outdated

Comment thread site/source/docs/compiling/best_practices.rst Outdated

sbc100 force-pushed the best_practices branch from 407b7ab to 6ec37a2 Compare July 16, 2026 17:40

sbc100 commented Jul 16, 2026

View reviewed changes

kripken reviewed Jul 17, 2026

View reviewed changes

sbc100 force-pushed the best_practices branch from 6ec37a2 to 27b1fcd Compare August 10, 2026 22:32

hoodmane reviewed Aug 11, 2026

View reviewed changes

Comment thread site/source/docs/compiling/best_practices.rst Outdated

sbc100 force-pushed the best_practices branch 2 times, most recently from a282780 to b759f99 Compare August 25, 2026 19:44

[docs] Add a Best Practices section to the website. NFC

53d15d1

sbc100 force-pushed the best_practices branch from b759f99 to 53d15d1 Compare August 25, 2026 20:00

sbc100 requested a review from kripken August 25, 2026 20:03

sbc100 requested review from dschuff and hoodmane August 25, 2026 20:03

kripken reviewed Aug 26, 2026

View reviewed changes

	- Avoid long lists on the command line; Use the ``@filename`` instead (for
	- Avoid long lists on the command line; use a response file instead, with ``@filename`` (for

Uh oh!

Conversation

sbc100 commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dschuff left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sbc100 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbc100 Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kripken Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kripken Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sbc100 commented Jul 13, 2026 •

edited

Loading

sbc100 Jul 20, 2026 •

edited

Loading

kripken Aug 26, 2026 •

edited

Loading

kripken Aug 26, 2026 •

edited

Loading