FastStore Platform Analyzer

Static analysis tool for FastStore extensions.

Installation

1. Add the analyzer to your project:

pnpm add @vtex/fsp-analyzer

Usage

This guide explains how to integrate the FastStore Platform Analyzer (@vtex/fsp-analyzer) into your monorepo. The analyzer aims to provide static code analysis capabilities to ensure code safety and compliance with the standards agreed by the FastStore Platform team.

[!IMPORTANT] Your CLI must adhere to the FastStore Platform CLI specification in order to have the hooks available as well as the basic scaffolding for the modules. If you are unaware of how to do this, please refer to the FastStore Platform CLI Docs.

Understanding the hooks folder

The hooks folder is a special folder in the FastStore Platform ecosystem that allows you to add custom hooks to the development lifecycle. These hooks can be executed at different stages of the runtime, and you can use them to run your own custom code. There are a few hooks available, such as:

• preBuild: Runs before the build process
• postBuild: Runs after the build process
• preDev: Runs before the development server starts
• postDev: Runs after the development server starts

[!NOTE] The hooks are defined in the src/hooks folder, and are executed in the order of the file name. For example, preBuild.ts will run before postBuild.ts.

In this guide, we'll focus on preBuild, as it was considered during the spec meetings to be the most convenient for the analyzer.

1. Create a pre-build hook in your project:

import { FastStoreSandboxAnalyzer } from "@vtex/fsp-analyzer";

export async function preBuild() {
  const analyzer = new FastStoreSandboxAnalyzer();

  try {
    await analyzer.analyzeFiles({
      filePattern: "your-module/**/*.{js,ts,jsx,tsx,css,less,scss}",
      cssOptions: {
        allowedNamespaces: ["extension-"], // Array of allowed CSS namespace prefixes
        transformNonCompliant: true, // Whether to automatically fix non-compliant CSS
        defaultNamespace: "extension-", // Default namespace to add to selectors
        verbose: true, // Output details and write transformed files to disk
        overwriteTransformed: true, // Whether to overwrite existing transformed files
      },
    });
  } catch (error) {
    console.error("Pre-build static analysis failed:", error);
    throw error;
  }
}

2. Register the hook in your project's entry point:

export const hooks = {
  preBuild,
  // ... other hooks
};

3. Run your project:

pnpm run dev

4. Do a build:

pnpm run build

And that's it! You should see the analyzer output in the console.

Library Rundown

Available Rules

• DOM API Access Restrictions: Prevent access to DOM API (e.g. document, window, localStorage)
• CSS Containment Analysis: Prevent unsolicited usage of selectors and CSS variables (e.g :root, :host, :host-context)
• Third-Party Script Loading Detection: Prevent loading of third-party scripts (e.g. importScripts, eval, new Function)
• Core Element Modification Detection: Prevent modification of core elements (e.g. body, html, head)

Next Steps

For Extension Points

1. Integration Requirements

   • Update your build pipeline to include the analyzer
   • Define appropriate file patterns for your module
   • Handle analysis failures appropriately

2. Code Compliance

   • Ensure code follows sandboxing guidelines
   • Document any required exceptions
   • Test analysis on your codebase

For FastStore Platform

• Review and document required API changes
• Define custom rules for specific needs
• Maintain the analyzer as a package and be sensitive to the needs of the extension points

Best Practices

1. Integration

   • Always run analyzer in pre-build hooks
   • Use specific file patterns
   • Handle errors gracefully

2. Configuration

   • Document any custom rules
   • Version control your analyzer config
   • Regular updates of analyzer package

3. Maintenance

   • Regular testing of analyzer rules
   • Keep documentation updated
   • Report issues and edge cases to the FastStore Platform team through #team-faststore-platform-dev

Common Issues and Solutions

Known Issues

1. Performance with Large Codebases

This is being explored in our roadmap. As though this does not mean that the fsp-analyzer will deteriorate as the codebase gets larger, the response time will be impacted, since the time-to-compute won't be the same.

• Use specific file patterns
• Implement incremental analysis
• Consider splitting analysis into chunks

2. False Positives
   • Document exceptions
   • Use ignore patterns when necessary
   • Report to the FastStore Platform team through #team-faststore-platform-dev for refinements

Support and Resources

• Documentation: FastStore Platform Docs