Reusing Code in Endpoints and Components

How to create a directory to share common code between endpoints and components in the Aurora SDK

This guide explains organizing and leveraging the /src/shared directory to manage code, assets, and utilities shared between your API endpoints and React components. Centralizing common resources can enhance maintainability, reduce code duplication, and ensure consistency across your project.

Overview

The /src/shared directory is designed to hold all reusable code, including utilities, styles, and GraphQL queries. This centralized approach enables both API endpoints and React components to easily access and maintain common functionality, improving development efficiency.

Folder Structure

Organize the /src/shared directory into logical subfolders as illustrated below:

/src
│── shared/               # Shared modules and resources
│   ├── component-utils/  # React component utilities
│   │   ├── index.tsx
│   │   ├── package.json  # Module dependencies and metadata
│   ├── endpoint-utils/   # API endpoint utilities
│   │   ├── index.ts
│   │   ├── package.json  # Module dependencies and metadata
│   ├── generic-utils/    # General-purpose utility functions
│   │   ├── index.ts
│   │   ├── package.json  # Module dependencies and metadata
│   ├── queries/          # Common GraphQL queries
│   │   ├── self.graphql
│   ├── styles/           # Shared CSS or PostCSS files
│       ├── styles.pcss
│── endpoints/            # Custom API endpoints
│── components/           # Custom React components

This structure helps keep shared resources well-organized and makes it easier to locate and reuse code.

How to Use the Shared Directory

Defining Shared Modules

Each module inside /src/shared should have its own package.json file. This file declares the module's metadata and dependencies, ensuring that shared code is versioned and maintained independently.

Example: component-utils

{
  "name": "@shared/component-utils",
  "version": "1.0.0",
  "main": "index.tsx",
  "private": true
}

Example: endpoint-utils

{
  "name": "@shared/endpoint-utils",
  "version": "1.0.0",
  "main": "index.ts",
  "private": true
}

Integrating Shared Modules into Your Project

To reuse shared modules, add them as dependencies in the package.json file of your API endpoint or React component projects.

For an API Endpoint

{
  "name": "@customer/sample-endpoint",
  "version": "1.0.0",
  "dependencies": {
    "@shared/endpoint-utils": "*",
    "@shared/generic-utils": "*"
  }
}

For a React Component

{
  "name": "@customer/sample-component",
  "version": "1.0.0",
  "dependencies": {
    "@shared/component-utils": "*",
    "@shared/generic-utils": "*"
  }
}

This approach ensures that the shared code is properly versioned and that any changes in shared modules are propagated throughout your project.

Working with GraphQL Queries

GraphQL queries that are common across endpoints and components should be stored in the /src/shared/queries folder.

GraphQL Query Example

query Self {
  self {
    id
    login
    email
  }
}

Usage in an Endpoint

import graphqlQuery from '@shared/queries.graphql';

This setup centralizes your GraphQL queries, making them easier to update and maintain over time.

Utilizing Shared Utility Functions and Styles

Place reusable functions in /src/shared under an appropriate folder such as generic-utils.

Shared Utility Functions

Place general-purpose functions in the generic-utils folder. These utilities can be imported and used across different parts of your application.

Utility Function Example (generic-utils/index.ts)

function formatText(text: string) {
  return `Formatted: ${text}`;
}
export default formatText;

Usage in an Endpoint

import formatText from '@shared/generic-utils';
log.info(formatText('example text'));

Shared Styles

Centralize shared CSS or PostCSS files in the styles folder to maintain consistency in styling.

CSS Example (styles/styles.pcss)

.test-style {
  border: 2px solid #ee6820;
}

Usage in a React Component

import styles from '@shared/styles.pcss';

Troubleshooting

Troubleshooting Checklist

• Ensure that each shared module’s package.json references the correct dependencies.
• Confirm GitHub Actions picks up changes in the /shared/ directory.
• Test endpoints and components using shared modules before merging/deploying.

Common Problems

Issue	Description	Fix
Missing or Incorrect main Field in package.json	If the main field is missing or points to a non-existent file, importing the module fails.	Ensure main exists and points to a real file.
Absent index.ts File in Modules with Only Styles or GraphQL	Even non-JS-only modules need an index.ts file.	Add a stub index.ts with export {}.
Incorrect Import Paths	Incorrect paths can result in "Cannot find module" errors.	Use accurate relative or scoped import paths.
Case Sensitivity Issues	Works on Windows, fails on Linux due to case mismatch.	Keep casing consistent in file names and imports.
Missing Dependencies	Errors from importing packages not installed.	Ensure packages are listed in dependencies and installed.
Incorrect TypeScript Configuration	Misconfigured tsconfig.json leads to resolution errors.	Check baseUrl, paths, and module settings.
Inconsistent Module Systems	Mixing CommonJS (require) and ESM (import) can break builds.	Stick to one system and align type in package.json accordingly.

Dependency References

• Ensure accuracy: Verify that each module’s package.json correctly lists all required dependencies.
• Consistency: Use consistent naming conventions for shared modules to avoid conflicts.

CI/CD Integration

• Detection: Configure your CI/CD pipelines (e.g., GitHub Actions) to monitor changes in the /src/shared directory. This helps catch integration issues early.

Testing

• Thorough testing: Ensure that endpoints and components utilizing shared resources are thoroughly tested.
• Integration checks: Run integration tests to verify that shared code works seamlessly across different parts of your project.