diff --git a/README.md b/README.md index 97fa6b1fe..6496255c6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,131 @@ -# aws-pdk + + +# Getting started + +## What is the AWS PDK? + +The AWS Project Development Kit (AWS PDK) provides building blocks for common patterns together with development tools to manage and build your projects. + +The AWS PDK lets you define your projects programatically via the expressive power of type safe constructs available in one of 3 languages (typescript, python or java). This approach yields many benefits, including: + +- Ability to set up new projects within seconds, with all boilerplate already pre-configured. +- Receive updates to previously bootstrapped projects when new versions become available i.e: updated dependenies or lint configurations. +- Build polyglot monorepos, with build caching, cross-language build dependencies, dependency visualization and much more. +- Leverage codified patterns which vend project and infrastructure (CDK) code. + +The AWS PDK is built on top of [Projen](https://github.com/projen/projen) and as such all constructs that you compose together need to be defined via a [projenrc](https://projen.io/programmatic-api.html) file. + +## Why use the AWS PDK? + +It's much easier to show than explain! Here is some PDK code (within projenrc file) that creates a Polyglot monorepo, with a React Website pre-configured with Cognito Auth and pre-integrated with a Smithy Type Safe Api. + +```ts +import { CloudscapeReactTsWebsiteProject } from "@aws/pdk/cloudscape-react-ts-website"; +import { InfrastructureTsProject } from "@aws/pdk/infrastructure"; +import { MonorepoTsProject } from "@aws/pdk/monorepo"; +import { + DocumentationFormat, + Language, + Library, + ModelLanguage, + TypeSafeApiProject, +} from "@aws/pdk/type-safe-api"; +import { javascript } from "projen"; + +const monorepo = new MonorepoTsProject({ + name: "my-project", + packageManager: javascript.NodePackageManager.PNPM, + projenrcTs: true, +}); + +const api = new TypeSafeApiProject({ + parent: monorepo, + outdir: "packages/api", + name: "myapi", + infrastructure: { + language: Language.TYPESCRIPT, + }, + model: { + language: ModelLanguage.SMITHY, + options: { + smithy: { + serviceName: { + namespace: "com.aws", + serviceName: "MyApi", + }, + }, + }, + }, + runtime: { + languages: [Language.TYPESCRIPT], + }, + documentation: { + formats: [DocumentationFormat.HTML_REDOC], + }, + library: { + libraries: [Library.TYPESCRIPT_REACT_QUERY_HOOKS], + }, + handlers: { + languages: [Language.TYPESCRIPT], + }, +}); + +const website = new CloudscapeReactTsWebsiteProject({ + parent: monorepo, + outdir: "packages/website", + name: "website", + typeSafeApi: api, +}); + +new InfrastructureTsProject({ + parent: monorepo, + outdir: "packages/infra", + name: "infra", + cloudscapeReactTsWebsite: website, + typeSafeApi: api, +}); + +monorepo.synth(); +``` + +This code (also available in Python and Java), produces all the source code, packages and infrastructure needed to deploy a fully-operable application in the AWS cloud. All that's left to do is build and deploy it! + +From this ~70 lines of code above, the AWS PDK produces the following packages on your behalf: + +- `monorepo`: Root level project that manages interdependencies between projects within the Monorepo, provides build caching and dependency visualziation. +- `api/model`: A project that allows you to define your API using Smithy (or OpenAPI) IDL. +- `api/generated/documentation`: A project that automatically creates API documentation in a variety of formats. +- `api/generated/infrastructure`: A project that automatically creates API infrastructure constructs in a type-safe manner. +- `api/generated/libraries`: A project that automatically generates a react hooks library that can be used to call your API from a React based website. +- `api/generated/runtime`: A project that contains server bindings for handlers to ensure type safety. +- `api/handlers`: A project that automatically creates handler stubs, preconfigured with type-safety and a variety of value added features based on your defined API's. +- `website`: A project which creates a React based website built using [Cloudscape](https://cloudscape.design/) that comes pre-integrated with Cognito Auth and your created API. This provides you with the ability to call your API securely. +- `infra`: A project which sets up all CDK related infrastructure needed to deploy your application. It also comes pre-configured to generate a diagram based on your CDK code everytime you build. + +### Bootstrapped Source + + + +### Generated Website + + + +### Generated Diagram + + + +As you can see, the AWS PDK provides you with valuable time savings so you can focus on working on what matters most to your project. + +## Developing with the AWS PDK + +Please refer to the full documentation website. https://aws.github.io/aws-pdk +## Contributing to the AWS PDK + +https://aws.github.io/aws-pdk/contributing/index.html + ## License This project is licensed under the Apache-2.0 License. diff --git a/docs/content/assets/images/rebrand_banner.png b/docs/content/assets/images/rebrand_banner.png new file mode 100644 index 000000000..8378f6e2b Binary files /dev/null and b/docs/content/assets/images/rebrand_banner.png differ diff --git a/docs/content/contributing/index.md b/docs/content/contributing/index.md index 4fb43b749..188491ffb 100644 --- a/docs/content/contributing/index.md +++ b/docs/content/contributing/index.md @@ -16,7 +16,8 @@ This is where the documentation site is defined and built. Contains configurations for each project within this monorepo. -**_As a rule of thumb, every package in the monorepo should correspond to a file in this directory._** +!!!info + As a rule of thumb, every package in the monorepo should correspond to a file in this directory. ### **packages** @@ -214,7 +215,7 @@ From the root directory run: `pdk upgrade-deps`. This will bump all dependencies If you run into an issue that resembles: ```bash -Type 'import(".../@aws/pdk/node_modules/aws-prototyping-sdk/node_modules/projen/lib/ignore-file").IgnoreFile' is not assignable to type 'import(".../@aws/pdk/node_modules/projen/lib/ignore-file").IgnoreFile'. +Type 'import(".../@aws/pdk/node_modules/@aws/pdk/node_modules/projen/lib/ignore-file").IgnoreFile' is not assignable to type 'import(".../@aws/pdk/node_modules/projen/lib/ignore-file").IgnoreFile'. Types have separate declarations of a private property '_patterns'. ``` diff --git a/docs/content/getting_started/shopping_list_app.md b/docs/content/getting_started/shopping_list_app.md index 17cebbb95..582cbe330 100644 --- a/docs/content/getting_started/shopping_list_app.md +++ b/docs/content/getting_started/shopping_list_app.md @@ -30,6 +30,9 @@ This is a continuation from [build your first AWS PDK project](./your_first_aws_ In order to define our API, we need to write some [Smithy](https://smithy.io/2.0/quickstart.html) code which is contained within `packages/api/model/src/main/smithy`. +!!!info + More detailed information on how to use smithy can be found in the [Type Safe API Developer Guide](../developer_guides/type-safe-api/using_smithy.md) + ### Definining our types Firstly, let's define some types for our Shopping List application by creating the following files: diff --git a/docs/content/overrides/home.html b/docs/content/overrides/home.html index b0f9cdfd2..67e373654 100644 --- a/docs/content/overrides/home.html +++ b/docs/content/overrides/home.html @@ -371,7 +371,7 @@
Getting started
- +