Gathering detailed insights and metrics for @fluid-tools/build-cli
Gathering detailed insights and metrics for @fluid-tools/build-cli
Gathering detailed insights and metrics for @fluid-tools/build-cli
Gathering detailed insights and metrics for @fluid-tools/build-cli
npm install @fluid-tools/build-cli
Fluid Framework v2.10.0 (minor)
Published on 19 Nov 2024
Fluid Framework v2.5.0 (minor)
Published on 05 Nov 2024
Fluid Framework v2.4.0 (minor)
Published on 15 Oct 2024
build-tools v0.49.0 (minor)
Published on 15 Oct 2024
build-tools v0.48.0 (minor)
Published on 15 Oct 2024
build-tools v0.47.0 (minor)
Published on 08 Oct 2024
Module System
Min. Node Version
Typescript Support
Node Version
NPM Version
4,744 Stars
21,414 Commits
535 Forks
78 Watching
459 Branches
246 Contributors
Updated on 27 Nov 2024
TypeScript (88.91%)
JavaScript (10.14%)
HTML (0.85%)
Dockerfile (0.05%)
Shell (0.03%)
Mustache (0.01%)
Cumulative downloads
Total Downloads
Last day
-60.4%
113
Compared to previous day
Last week
-58%
605
Compared to previous week
Last month
-3.7%
4,885
Compared to previous month
Last year
-13%
59,300
Compared to previous year
61
37
The Fluid Framework is a library for building distributed, real-time collaborative web applications using JavaScript or TypeScript.
You may be here because you want to...
Documentation and guides can be found at https://fluidframework.com/.
Hello World repo can be found at https://github.com/microsoft/FluidHelloWorld.
Core Examples repo can be found at https://github.com/microsoft/FluidExamples.
Have questions? Engage with other Fluid Framework users and developers in the Discussions section of our GitHub repo.
When taking a dependency on a Fluid Framework library's public APIs, we recommend using a ^
(caret) version range, such as ^1.3.4
.
While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
library consumers should always prefer ^
.
If using any of Fluid Framework's unstable APIs (for example, its beta
APIs), we recommend using a more constrained version range, such as ~
.
The core code for both the Fluid client packages and the reference ordering service is contained within this repo.
The repo structure is somewhat unique because it contains several pnpm workspaces: some for individual packages and some for larger collections which we call "release groups". The workspaces are versioned separately from one another, but internally all packages in a workspaces are versioned together.
These workspaces do not align with package namespaces, and also don't always correspond to a single directory of this repo.
Here's the list of release group workspaces:
@fluidframework/
namespace, but some in @fluid-tools
and unpublished packages in @fluid-internal/
)@fluid-experimental/
namespace)@fluid-example/
namespace)@fluidframework/
namespace)@fluidframework/
namespace)@fluidframework/
namespace)@fluidframework/
namespace)@fluidframework/
and @fluid-tools/
namespaces)Here's a list of other sets of other packages (each package within these groups is versioned independently, forming its own release group):
@fluidframework/
namespace. Most of these (but not all) have "common" in their package name.
Packages which are used by multiple other groups of packages (such as built tools, linter configs and protocol definitions) live here.@fluidframework/
namespace)Dependencies between packages in various layers of the system are enforced via a build step called layer-check. You can view the full list of packages and layers in PACKAGES.md.
PACKAGES.md
for local package changes, run pnpm layer-check --md .
.Install the required tools:
Clone a copy of the repo and change to the repo root directory:
1git clone https://github.com/microsoft/FluidFramework.git 2cd FluidFramework
Enable NodeJs's corepack:
1corepack enable
Run the following to build the client packages:
1pnpm install 2npm run build
You can use the experimental worker mode to get faster build time as well: npm run build:fast
See also: Contributing
To build Fluid Framework within VSCode, open the Fluid Framework repo folder as a work space and use Ctrl-Shift-B
to activate the build task. It is the same as running npm run build
on the command line.
We recommend using nvm (for Windows or MacOS/Linux) or fnm to install Node.js. This ensures you stay at the correct version while allowing other uses of NodeJS to use the (possibly different) versions they need side-by-side.
Because of a transitive dependency on a native addon module, you'll also need to ensure that you have the prerequisites for node-gyp
.
Depending on your operating system, you'll have slightly different installation requirements (these are largely copied from node-gyp
's documentation):
The node installer should ask if you want to install "Tools for Native Modules." If you check the box for this nothing further should be needed. Otherwise, you can follow the steps listed here
make
If you've upgraded your Mac to Catalina or higher, you may need to follow these instructions.
XCode Command Line Tools
, which will install make
, clang
, and clang++
xcode-select --install
from a command line.server
(e.g. fluid-build --symlink:full
).There are a few different areas in which we generate documentation content as a part our overall build.
docs
directory under the root of this repo.
See its README for more details.npm run build:readme
from the repo root.npm run build:api
from the repo root.This section contains common workflows and patterns to increase inner dev loop efficiency.
pnpm install
from the root of the repository to install dependencies. This is necessary for new clones or after pulling changes from the main branch.
pnpm run build:fast
from the root of the repository to perform an incremental build that matches the CI build process. Incremental builds tend to leave extra files laying around, so running a clean is sometimes needed to cleanup ghost tests
pnpm run build:fast -- <path>
to build only a specific part of the repository.
pnpm run build
within a package directory to build that package.
pnpm run build:compile
for cross-package compilation.
pnpm run format
to format the code.
fluid-build --vscode
to output error message to work with default problem matcher in vscode. If fluid-build
is not installed, please install it with npm i -g @fluidframework/build-tools
.
fluid-build -t build <NAME_OF_PACKAGES>
to build a multiple space-separated packages along with all their dependencies. If fluid-build
is not installed, please install it with npm i -g @fluidframework/build-tools
.You can also use the VSCode JS debug terminal, then run the test as normal.
Sometimes, uncommitted changes can cause build failures. Committing changes might be necessary to resolve such issues.
pnpm clean
if random build failures, especially with no changesgit clean -xdf
to remove extraneous files if debugging becomes slow or hangs.You can run all of our tests from the root of the repo, or you can run a scoped set of tests by running the test
command from the package you're interested in.
Note: Some of the tests depend on test collateral that lives in a submodule here: https://github.com/microsoft/FluidFrameworkTestData. You may choose to fetch that collateral into your local repository, which is required to run all the tests - otherwise some will be skipped.
First, ensure you have installed Git LFS. Then, from the repo root:
1git lfs install 2git submodule init 3git submodule update
Before running the tests, the project has to be built. Depending on what tests you want to run, execute the following command in the package directory or at the root:
1npm run test
To run a single test within a module, add .only
to it
or describe
. To exclude a test, use .skip
.
You can use ts-mocha
to quickly run specific test files without needing to make the whole project compile. For more details on test filtering using CLI arguments, refer to the Mocha documentation.
Our test setup generally requires building before running the tests.
Incremental builds may leave extra files, which can result in ghost tests. To avoid this, consider running a clean build with the following command:
1pnpm clean <package>
This removes any leftover files from previous builds, providing a clean testing environment.
1npm run test:coverage
Our CI pipelines run on Linux machines, and the npm scripts all have the ci
prefix.
To replicate the test steps from the CI pipeline locally, run the following commands for the packages or pnpm workspaces:
Run | Non-Windows | Windows |
---|---|---|
PR | npm run ci:test | npm run test:report && npm run test:copyresults |
Official | npm run ci:test:coverage | npm run test:coverage && npm run test:copyresults |
We've checked in VS Code configuration
enabling F5 from a spec.ts
file to run those tests if you set the debug configuration to "Debug Current Test".
This will use an in-memory implementation of the Fluid server to sync between the two panes in the browser window.
/examples
/examples/data-objects/clicker
npm run start
This will run the local Fluid server implementation we call "Tinylicious", so you can sync between multiple browser instances.
First, start Tinylicious by running these commands from /server/routerlicious/
:
1pnpm install
Then these commands from /server/routerlicious/packages/tinylicious
:
1pnpm run build 2pnpm run start
Then:
npm run start:tinylicious
This repository uses prettier as its code formatter. Right now, this is implemented on a per-package basis, with a shared base configuration.
prettier
on your code, run npm run format
from the appropriate package or release group, or run
npm run format:changed
from the root of the repo to format only files changed since the main branch.
If your change is for the next branch instead, you can run npm run format:changed:next
.prettier
with fluid-build, you can specify "format" via the
script argument: fluid-build -t format
or npm run build:fast -- -t format
To ensure our formatting remains consistent, we run a formatting check as a part of each package's lint
script.
Our workspace configuration specifies prettier
as the default formatter.
Please do not change this.
It is not configured to do any formatting automatically, however. This is intentional, to ensure that each developer can work formatting into their workflow as they see fit. If you wish to configure your setup to format on save/paste/etc., please feel free to update your user preferences to do so.
Notable setting options:
format on save
format on paste
Run the following command in each of your repositories to ignore formatting changes in git blame commands:Â git config --local blame.ignoreRevsFile .git-blame-ignore-revs
The root package.json in the repo includes devDependencies on the mocha and jest testing tools. This is to enable easier test running and debugging using VSCode. However, this makes it possible for projects to have a 'phantom dependency' on these tools. That is, because mocha/jest is always available in the root, projects in the repo will be able to find mocha/jest even if they don't express a dependency on those packages in their package.json. We have lint rules in place to prevent phantom dependencies from being introduced but they're not foolproof.
There are many ways to contribute to Fluid.
Detailed instructions for working in the repo can be found in the Wiki.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
No vulnerabilities found.
Reason
30 commit(s) and 3 issue activity found in the last 90 days -- score normalized to 10
Reason
all changesets reviewed
Reason
no dangerous workflow patterns detected
Reason
security policy file detected
Details
Reason
license file detected
Details
Reason
no binaries found in the repo
Reason
dependency not pinned by hash detected -- score normalized to 8
Details
Reason
branch protection is not maximal on development and all release branches
Details
Reason
9 existing vulnerabilities detected
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
Project has not signed or included provenance with any releases.
Details
Reason
project is not fuzzed
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
Score
Last Scanned on 2024-11-18
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More