Harvmaster/xo-stack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Misc Playground/Docs fixes

Browse Source
This commit is contained in:
Jim Hamill
2025-07-15 04:07:59 +00:00
parent 39e2d4b991
commit f71100b28c
13 changed files with 87 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+13 -2
View File
@@ -77,7 +77,7 @@ These guidelines represent best practices. While exceptions may occasionally be
- Often mask underlying issues that should be properly resolved
- Can lead to unintended side-effects throughout the codebase
4. Avoid additional dependencies.
5. Avoid additional dependencies.
Try to avoid pulling in additional packages. Not only can this bloat the project, but can also cause compatibility issues between environments (Web, Node, ESM, etc). We want `@xocash/stack` to "just work" without devs having to tailor build configurations.
@@ -87,7 +87,18 @@ These guidelines represent best practices. While exceptions may occasionally be
- Does not drag in additional dependencies itself (note that `devDependencies` are fine. These will not be installed when leveraged from our packages).
- If the package being used **is heavy** and we have no other choice but to use it, consider whether we should package it separately to avoid problems. For example, if we build a `BlockchainBCHN` adapter, we will likely want to package this on its own under `@xocash/blockchain-bchn` as it only works in NodeJS environments.
5. "When in Rome..."
6. DO NOT use Typescript "enums".
TypeScript enums have several issues that make them problematic:
- They generate unnecessary runtime code and don't tree-shake well, increasing bundle size
- Numeric enums allow unsafe reverse lookups and can be assigned any number value
- They don't work well with module augmentation and can cause circular dependency issues
- They're not compatible with Node.js's --experimental-strip-types feature, which only removes type annotations and doesn't transform enum syntax
Recommended alternatives: Use const objects with `as const` assertions or string literal union types instead, which work seamlessly with Node's type stripping.
7. "When in Rome..."
For conventions not explicitly mentioned, follow the "when in Rome" principle. Try to identify and use the patterns and conventions that are already established elsewhere in the codebase.