@syss/arch-archetype-base-backend NPM

BASE ARCHETYPE README

BASE ARCHETYPE README

This README would typically document the necessary steps to get your application up and running.

Description

This project is a backend archetype that provides the structure and organization within the architecture. It's developed in ES2015 with CDK and TypeScript, and includes unit tests using Jest. Code review is performed with ESLint using the SonarQube plugin to adhere to best practices. We recommend using VSCode for working on the project, although we also provide configuration for IntelliJ IDEA if you prefer Java.

Key features of this project include:

ECMAScript 2015 (ES6): This project takes full advantage of modern JavaScript syntax and features, offering enhanced readability and maintainability.
AWS CDK: The project leverages the AWS CDK, a powerful framework for defining cloud infrastructure as code, to facilitate the provisioning and management of AWS resources.
Unit Testing with Jest: Robust unit tests have been implemented using Jest, a popular JavaScript testing framework. These tests help ensure the reliability and correctness of the codebase.
Code Quality Assurance with ESLint: The codebase is rigorously checked for coding standards and potential issues using ESLint. Additionally, the project integrates the SonarQube ESLint plugin, which enforces rules aligned with SonarQube's best practices, further enhancing code quality.

This backend archetype is designed to provide a solid foundation for your architecture projects, offering modern development practices, thorough testing, and robust code quality assurance. It empowers you to build scalable and maintainable APIs with ease.

CDK

AWS CDK (Cloud Development Kit) is an open-source framework by Amazon Web Services (AWS) that simplifies cloud infrastructure provisioning. It lets developers define and deploy AWS resources using familiar programming languages, making it easier to manage and automate cloud infrastructure as code.

Run and Debug Details

To run AWS CDK in debug mode using Visual Studio Code (VSCode), follow these steps:

Open your CDK project in VSCode:
- Open Visual Studio Code and select the root folder of your CDK project from the "File" > "Open Folder" menu.
Configure the launch.json file:
- If you don't already have a launch configuration file (launch.json), you can create one by clicking on the "Run and Debug" tab in the left sidebar of VSCode and selecting "Add Configuration...". From there, you can choose a suitable template for CDK.
Set up the launch configuration:
- In the launch.json file, configure the launch configuration for CDK debug mode. You may need to specify the entry point or main file for your CDK application and other relevant settings.
Set breakpoints:
- In your CDK code, place breakpoints on the lines where you want the execution to pause for debugging purposes. You can do this by clicking in the left margin of the code editor next to the line numbers.
Start debugging:
- In the VSCode interface, select your CDK debug configuration from the dropdown in the top toolbar.
- Click the green "play" button to start debugging.
Debugging session:
- When your CDK application reaches a breakpoint, the execution will pause, and you can inspect variables, step through code, and use VSCode's debugging features to analyze and troubleshoot your application.

By following these steps, you can run AWS CDK in debug mode and effectively debug your CDK application using Visual Studio Code.

Jest

Jest is a popular JavaScript testing framework that is widely used for unit testing and test-driven development (TDD). It is an open-source tool developed by Facebook and is particularly well-suited for testing JavaScript applications, including web applications, Node.js applications, and more.

Run and Debug details

To use, run, and debug tests in Jest, follow these steps:

Write Your Tests:
- Create test files with a .test.js, .test.ts, or .spec.js, .spec.ts extension. Jest will automatically find and run these files. Write your test cases using Jest's testing framework.
Add Test Scripts to package.json:
- Open your project's package.json file and add test scripts. For example:
```
"scripts": {
  "test": "jest"
}
```
Run Tests:
- To run your tests, execute the following command in your terminal:
```
npm test
```
or
```
yarn test
```
This will run Jest and execute all test files in your project.
Debug Tests in VSCode:
- If you're using Visual Studio Code (VSCode), you can debug your Jest tests easily. Follow these steps:
a. Open the test file you want to debug in VSCode.
b. Set breakpoints in your test file by clicking in the left margin next to the line numbers where you want to pause execution.
c. Create a debug configuration for Jest. In your project's .vscode folder, create a launch.json file if it doesn't exist, and add a configuration like this:
```
{
  "type": "node",
  "request": "launch",
  "name": "Jest Current File",
  "program": "${workspaceFolder}/node_modules/jest/bin/jest",
  "args": [
    "${relativeFile}"
  ],
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen"
}
```
d. Open the test file you want to debug, select the Jest debug configuration you just created from the dropdown in the top toolbar, and click the green "play" button to start debugging.
e. Jest will run in debug mode, and when it encounters a breakpoint, it will pause execution, allowing you to inspect variables and step through your test code.

Now you can write, run, and debug tests in Jest with ease using Visual Studio Code or your preferred development environment.

ESLint

ESLint is a widely used open-source static code analysis tool for JavaScript, with support for ECMAScript 2015 (ES6) and later versions. It is designed to help developers maintain code quality, catch potential issues, and enforce coding standards. Here's a summary of ESLint's key features, along with a mention of its compatibility with ECMAScript 2015 (ES6) and the SonarQube plugin:

Code Quality Analysis: ESLint analyzes your JavaScript code statically to identify and report on code quality issues, potential bugs, and coding style violations. It helps maintain a high code quality standard within your projects.
Customizable Rules: ESLint allows you to configure and customize rules based on your project's specific coding guidelines and preferences. You can enable, disable, or modify rules to match your team's coding standards.
ES6 Support: ESLint fully supports ECMAScript 2015 (ES6) and later versions, making it compatible with modern JavaScript syntax and features. It can analyze code that uses features like arrow functions, destructuring, and template literals.
Plugin System: ESLint has a rich ecosystem of plugins and extensions that provide additional rules and integrations. The SonarQube plugin, for example, extends ESLint's capabilities to integrate with SonarQube for even more comprehensive code analysis and reporting.
Integration with Build Tools: ESLint seamlessly integrates with popular build tools and development environments, such as Webpack, Babel, and Visual Studio Code, allowing you to incorporate code analysis into your development workflow.
Automatic Code Formatting: While ESLint primarily focuses on code analysis, it can work in tandem with code formatters like Prettier to automatically format your code according to defined rules, ensuring consistent coding style.
Configurable Configurations: ESLint configurations can be shared across projects to maintain consistency. You can create and share ESLint configuration files, making it easy to enforce coding standards across multiple codebases.
Continuous Integration (CI) Integration: ESLint is often integrated into CI/CD pipelines to enforce code quality and style standards automatically, preventing low-quality code from being merged into the codebase.

Run details

To set up ESLint and configure it to use the "plugin:sonarjs/recommended" plugin for SonarQube rules, follow these steps:

Install ESLint:
- If you haven't already installed ESLint, you can add it as a development dependency to your project using npm or yarn:
```
npm install --save-dev eslint
```
or
```
yarn add --dev eslint
```
Create ESLint Configuration:
- You can create an ESLint configuration file in the root of your project. Typically, this file is named .eslintrc.js or .eslintrc.json. Here's an example .eslintrc.js configuration file that includes the "plugin:sonarjs/recommended" plugin:
```
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:sonarjs/recommended', // Include SonarQube recommended rules
  ],
  parserOptions: {
    ecmaVersion: 2015, // Set your ECMAScript version (ES2015 in this case)
  },
  rules: {
    // Additional project-specific ESLint rules can be added here
  },
};
```
Customize the ESLint rules to fit your project's requirements by adding or modifying rules in the rules section.
Install SonarQube Plugin:
- Ensure you have the "eslint-plugin-sonarjs" plugin installed. If it's not already installed, you can add it as a development dependency:
```
npm install --save-dev eslint-plugin-sonarjs
```
or
```
yarn add --dev eslint-plugin-sonarjs
```
Run ESLint:
- You can now run ESLint to analyze your code based on the configured rules. Use the following command:
```
npx eslint . --fix
```
The --fix flag automatically fixes some of the linting errors if possible.
Integrate with Your IDE (Optional):
- Many code editors and IDEs offer ESLint integrations that provide real-time linting feedback as you write code. If you're using Visual Studio Code, you can install the "ESLint" extension to get these features.

With this setup, ESLint will enforce the rules defined in your configuration, including the SonarQube rules from the "plugin:sonarjs/recommended" preset. Make sure to address any ESLint warnings and errors in your code to adhere to the defined coding standards and best practices.

Note: Any configuration during execution should be done in the package.json file.

IDEA

The .idea file contains the basic configuration for Java projects using the IntelliJ IDEA IDE.

CDK debug details To enable debugging mode in IntelliJ IDEA for a Java project using Amazon's AWS CDK (Cloud Development Kit), follow these steps:

Open Your Project in IntelliJ IDEA:
- Launch IntelliJ IDEA.
- Open your Java project that uses AWS CDK.
Configure Run Configuration:
- At the top of the IntelliJ IDEA window, look for and click on the "Run" menu.
- Select "Edit Configurations" from the dropdown. This will open the Run/Debug Configurations window.
Add a New Run Configuration:
- In the Run/Debug Configurations window, click on the "+" icon in the upper left corner and select "Application" from the dropdown.
Configure the New Run Configuration:
- In the "Name" section, provide a descriptive name for this run configuration (e.g., "CDK Debug").
- In the "Main class" section, specify the main class of your CDK application. This is typically the class that contains the main method that starts your CDK application.
Configure Debugging Options:
- In the "Use classpath of module" section, select the module of your project that contains your CDK code.
- In the "Before launch" section, you can configure any pre-launch tasks, such as building the project if necessary.
Configure Remote Debugging Options:
- In the "Build and run using" section, select "Debug."
- In the "Use classpath of module" section, choose the same module you selected in the previous step.
- You can configure other options as needed.
Apply and Save the Configuration:
- Click "Apply" and then "OK" to save the run configuration.
Start Debugging:
- At the top of IntelliJ IDEA, select the run configuration you just created from the run configuration dropdown.
- Click the green "bug" icon to start debugging.
Set Breakpoints:
- In your CDK code, place breakpoints on the lines where you want the execution to pause so that you can examine the application's state.
Start the Application with Debugging:
- Run your CDK application by clicking the "play" icon or start your application in the usual way.
Execution Will Halt at Breakpoints:
- When the application reaches a breakpoint, execution will pause, allowing you to inspect variables and the application's state in the IntelliJ IDEA debug window.

By following these steps, you will have enabled debugging mode for your Java application using AWS CDK in IntelliJ IDEA. You can utilize IntelliJ IDEA's debugging capabilities to effectively inspect and debug your code.

Note: Any configuration during execution should be done in the package.json file.

Package file

This package.json file serves as a configuration file for an AWS CDK (Cloud Development Kit) project. It defines various scripts and dependencies used in the project's development and testing processes. The scripts defined in this file automate common development tasks, making it easier to manage and maintain the project. The file also lists both runtime and development dependencies required for building and testing the project.

Additionally, this package.json file is part of the project's version control and development environment setup, ensuring consistency and reproducibility across different development environments and facilitating collaboration among team members.

Here's a brief explanation of the commands in the scripts section of that package.json:

build: This command runs the TypeScript compiler (tsc) to compile TypeScript source code into JavaScript. It's useful for building the application.
watch: Similar to the "build" command, but in watch mode. This means it will stay running and automatically recompile when changes to source files are detected.
test: Executes tests using Jest, a JavaScript testing framework. It also generates a code coverage report in the "COVERAGE.md" file.
test:cicd: Similar to the "test" command but without generating the coverage report. It may be useful for running tests in a CI/CD (Continuous Integration/Continuous Delivery) environment.
cdk: This command is used to run the CDK (Cloud Development Kit) commands, typically for managing AWS resources defined in your infrastructure as code.
lint: Runs ESLint, a static code analysis tool, to check TypeScript files for coding standards and issues based on the ESLint configuration.
eslint: Executes ESLint with the --fix option to automatically fix some of the linting issues in TypeScript files. It also enforces a maximum number of warnings (0 in this case).
tsdoc: Generates documentation using Typedoc, a documentation generator for TypeScript projects. It uses a markdown theme for the documentation.
lint:fix: Runs ESLint with the --fix option to automatically fix some of the linting issues in TypeScript files.

These scripts automate various development and testing tasks, making it easier to work with the project.

IntelliJ IDEA

The .idea file contains the basic configuration for Java projects using the IntelliJ IDEA IDE.

CDK Debug Details To enable debugging mode in IntelliJ IDEA for a Java project using Amazon's AWS CDK (Cloud Development Kit), follow these steps:
1. Open Your Project in IntelliJ IDEA:
  - Launch IntelliJ IDEA.
  - Open your Java project that uses AWS CDK.
2. Configure Run Configuration:
  - At the top of the IntelliJ IDEA window, look for and click on the "Run" menu.
  - Select "Edit Configurations" from the dropdown. This will open the Run/Debug Configurations window.
3. Add a New Run Configuration:
  - In the Run/Debug Configurations window, click on the "+" icon in the upper left corner and select "Application" from the dropdown.
4. Configure the New Run Configuration:
  - In the "Name" section, provide a descriptive name for this run configuration (e.g., "CDK Debug").
  - In the "Main class" section, specify the main class of your CDK application. This is typically the class that contains the main method that starts your CDK application.
5. Configure Debugging Options:
  - In the "Use classpath of module" section, select the module of your project that contains your CDK code.
  - In the "Before launch" section, you can configure any pre-launch tasks, such as building the project if necessary.
6. Configure Remote Debugging Options:
  - In the "Build and run using" section, select "Debug."
  - In the "Use classpath of module" section, choose the same module you selected in the previous step.
  - You can configure other options as needed.
7. Apply and Save the Configuration:
  - Click "Apply" and then "OK" to save the run configuration.
8. Start Debugging:
  - At the top of IntelliJ IDEA, select the run configuration you just created from the run configuration dropdown.
  - Click the green "bug" icon to start debugging.
9. Set Breakpoints:
  - In your CDK code, place breakpoints on the lines where you want the execution to pause so that you can examine the application's state.
10. Start the Application with Debugging:
  - Run your CDK application by clicking the "play" icon or start your application in the usual way.
11. Execution Will Halt at Breakpoints:
  - When the application reaches a breakpoint, execution will pause, allowing you to inspect variables and the application's state in the IntelliJ IDEA debug window.

Note: Any configuration during execution should be done in the package.json file.

@aws-solutions-constructs/core @syss/arch-archetype-utils @syss/arch-cdk-patterns aws-cdk-lib constructs fs js-yaml properties-reader

@everything-registry/sub-chunk-890

1.0.0

6 months ago