Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@architect/docs
Advanced tools
@architect/docs - npm Package Compare versions
Comparing version 30.1.11 to 30.1.12
| # Data | ||
| > Data is the core to most apps; `architect` favors DynamoDB for its flexability and ease of use | ||
| > Data is the core to most apps; `architect` favors DynamoDB for its flexibility and ease of use | ||
@@ -22,3 +22,3 @@ Given the following `.arc` file: | ||
| - further seperating reads from writes is a decent idea | ||
| - further separating reads from writes is a decent idea | ||
| - isolating stage data from prod data is not a horrible idea | ||
@@ -28,3 +28,3 @@ | ||
| Create a couple of modules `accounts` and `notes` to represent their corosponding tables: | ||
| Create a couple of modules `accounts` and `notes` to represent their corresponding tables: | ||
@@ -31,0 +31,0 @@ ```bash |
| # Sync Deps | ||
| > Shared deps is neccessary and having them go out of sync is an error prone condition. Reccomendation: out-of-date dependencies is a failing test! | ||
| > Shared deps is necessary and having them go out of sync is an error prone condition. Recommendation: out-of-date dependencies is a failing test! | ||
| You cannot opt-out of shared dependencies in an `.arc` project. There are many use cases for isolating code into shared modules: | ||
| - Seperating your data layer from your app is darn good idea | ||
| - Separating your data layer from your app is darn good idea | ||
| - Common view templates | ||
| - Shared content: translations, error codes, etc | ||
| And having lots of deps means having to manage lots of versions of packages: | ||
| And having lots of deps means having to manage lots of versions of packages: | ||
@@ -17,7 +17,7 @@ - `node_modules` in `.src` defined by `.arc` | ||
| Two things can happen: you can synchronize them all or you can let the drift. Just writing that down seemed completely silly but we did try the former and suffice to say your inital gut reaction was correct: it was not awesome. Precisely the opposite. I get it, microservices can be independant and this type of project sure feels like it can get away with that. The functions are completely isolated when deployed. However an `.arc` file *always* defines an `@app` namespace that **within that** all of your dependencies should be synchronized or you will eventually run into hard to trace bugs due to inconsistenties. | ||
| Two things can happen: you can synchronize them all or you can let the drift. Just writing that down seemed completely silly but we did try the former and suffice to say your initial gut reaction was correct: it was not awesome. Precisely the opposite. I get it, microservices can be independent and this type of project sure feels like it can get away with that. The functions are completely isolated when deployed. However an `.arc` file *always* defines an `@app` namespace that **within that** all of your dependencies should be synchronized or you will eventually run into hard to trace bugs due to inconsistencies. | ||
| The great news is there is an easy solution. Keep your modules in sync and ensure they stay that way by writing a failing test if they are not at the most recent published version. You *could* version lock but then you're opening yourself up bugs due to staleness. | ||
| The great news is there is an easy solution. Keep your modules in sync and ensure they stay that way by writing a failing test if they are not at the most recent published version. You *could* version lock but then you're opening yourself up bugs due to staleness. | ||
| Here is a hideous (but working!) dep checker tester for everything in `./src/json`. | ||
| Here is a hideous (but working!) dep checker tester for everything in `./src/json`. | ||
@@ -63,7 +63,7 @@ ```javascript | ||
| Ok, so your deps fell out of date and the build failed. | ||
| Ok, so your deps fell out of date and the build failed. | ||
| - Manually change into the shared dep directories and use `npm` normally | ||
| - For deps defined by `.arc` you can use [`@architect/modules`](/reference/npm-run-scripts#arc-modules) `npm run` scripts | ||
| - For deps defined by `.arc` you can use [`@architect/modules`](/reference/npm-run-scripts#arc-modules) `npm run` scripts | ||
| More complex projects will have unique build requirements which you can compose with Node or Bash as you see fit. We reccomend a `./scripts` folder for those particulars. | ||
| More complex projects will have unique build requirements which you can compose with Node or Bash as you see fit. We recommend a `./scripts` folder for those particulars. |
@@ -5,3 +5,3 @@ # Logging | ||
| - CloudWatch events offers a tonne of metrics | ||
| - X Ray offers deeper service call introspection capabilties | ||
| - X Ray offers deeper service call introspection capabilities | ||
| - There are many third party tools to further extend your app with structured logs |
@@ -31,5 +31,5 @@ # Community | ||
| If you are evaluating `architect` we also reccomend checking out: | ||
| If you are evaluating `architect` we also recommend checking out: | ||
| - [this space intentially blank for now! norobots] | ||
| - [this space intentionally blank for now! norobots] | ||
@@ -36,0 +36,0 @@ We believe open source should foster the spirit of science where we can respect, learn, and build on each others work. |
@@ -8,7 +8,7 @@ # Concepts | ||
| - The web console is confusing, with divergent interfaces between interlocking services | ||
| - Deep proprietary knowledge is required to configure and maintain common infrastructure primatives | ||
| - Deep proprietary knowledge is required to configure and maintain common infrastructure primitives | ||
| - Configuration and infrastructure can drift, leaving systems in states that are difficult to repeat / reproduce, and thus scale | ||
| - Painful manifest files; JSON is difficult to read, has no comments, and unforgiving to edit; YAML isn't much better and especially worse with deeply nested statements | ||
| _Some_ of these problems have been tamed with [infrastructure as code](https://en.wikipedia.org/wiki/Infrastructure_as_Code), creating repeatable and reproducable systems. | ||
| _Some_ of these problems have been tamed with [infrastructure as code](https://en.wikipedia.org/wiki/Infrastructure_as_Code), creating repeatable and reproducible systems. | ||
@@ -21,9 +21,9 @@ The tradeoff is you are committing AWS configuration knowledge into your revision control systems. | ||
| `architect` defines a simple plaintext format, `.arc`, as a manfiest file to solve the specific problems laid out above. | ||
| `architect` defines a simple plaintext format, `.arc`, as a manifest file to solve the specific problems laid out above. | ||
| With `architect`, you can: | ||
| - Focus on defining your app architecture with a subset of service primatives as high level defintions | ||
| - Focus on defining your app architecture with a subset of service primitives as high level definitions | ||
| - Use `npm scripts` to generate local code, configure, provision, and deploy cloud infrastructure from the `.arc` manifest | ||
| - You can still safely use the console tactically to access and administer primatives defined in `.arc` | ||
| - You can still safely use the console tactically to access and administer primitives defined in `.arc` | ||
| - The format, parser, and tooling are completely open to extension | ||
@@ -41,3 +41,3 @@ | ||
| `.arc` files are made up of the following sections: | ||
| `.arc` files are made up of the following sections: | ||
@@ -52,3 +52,3 @@ - `@app` defines the application namespace | ||
| This is a complete `.arc` file example: | ||
| This is a complete `.arc` file example: | ||
@@ -111,7 +111,7 @@ ```arc | ||
| `architect` follows many of the principles pioneered by agile and championed by devops. Versioning infrastructure. Tight feedback loops for dev, while maintaining isolation between stages. Systems that are consistent, inspectable, transparent, and exensible. | ||
| `architect` follows many of the principles pioneered by agile and championed by devops. Versioning infrastructure. Tight feedback loops for dev, while maintaining isolation between stages. Systems that are consistent, inspectable, transparent, and extensible. | ||
| ### Architecture as text | ||
| - `.arc` manifest file defines achitecture elements as plainly as possible in text | ||
| - `.arc` manifest file defines architecture elements as plainly as possible in text | ||
| - Nesting and syntax is deliberately constrained | ||
@@ -128,7 +128,7 @@ - And you can add comments! | ||
| - `arc-sandbox` allows you to work locally and offline from the cloud | ||
| - `arc-sandbox` allows you to work locally and offline from the cloud | ||
| - `arc-deploy` treats `staging` and `production` as first class concepts | ||
| - Deployment to `production` requires an extra manual step of setting `ARC_DEPLOY=production` env var | ||
| ### Extensible and flexibile systems | ||
| ### Extensible and flexible systems | ||
@@ -135,0 +135,0 @@ - `arc-parser` is open, and `architect` tooling ignores `@sections` it does not know |
@@ -9,4 +9,4 @@ # Limits | ||
| - Some things **Just Fail**, and you won't even always get a useful error | ||
| - This means: you _must_ consider retrys, including manual retrys, where you create / destory / recreate infra workflows (and, accordingly, `.arc` workflows are intended to be run and re-run) | ||
| - Some things **Just Fail**, and you won't even always get a useful error | ||
| - This means: you _must_ consider retries, including manual retries, where you create / destroy / recreate infra workflows (and, accordingly, `.arc` workflows are intended to be run and re-run) | ||
| - Yes, it's "kinda gross" but it does actually work works. Sometimes we call this situation *immutable infrastructure* to feel better! 💖 | ||
@@ -18,4 +18,4 @@ - Regions go down, and there isn't necessarily a great way to move them without a DNS change | ||
| - API Gateway API limits can be brutal, so creating http routes can be slow (i.e. generating a large amount of routes can take minutes) | ||
| - Cloudwatch logs are not structured (so we search for `console.log` strings instead of querying structured data – inspectability is hugely important for produciton systems) | ||
| - Lambdas cannot execute for longer than 5 minutes | ||
| - Cloudwatch logs are not structured (so we search for `console.log` strings instead of querying structured data - inspectability is hugely important for production systems) | ||
| - Lambdas cannot execute for longer than 5 minutes | ||
| - Lambda functions require you to `npm install` to your project `node_modules` individually prior to deployment | ||
@@ -25,11 +25,11 @@ | ||
| Most of these constraints where borne out of neccessity for speed; velocity aided by way of minimum essential capability. | ||
| Most of these constraints where borne out of necessity for speed; velocity aided by way of minimum essential capability. | ||
| These items will be great topics of community discussion and future contribution, so file them as: _maybe someday_. | ||
| These items will be great topics of community discussion and future contribution, so file them as: _maybe someday_. | ||
| - `PATCH`, `PUT`, `DELETE` are not suppported, but maybe they shouldn't be (100% support everthing browsers do: `GET` and `POST`) | ||
| - Routes must be unqiue (i.e. no overloading `Content-Type`); it's certainly possible to get around, but you probably don't want to do that anyhow | ||
| - `PATCH`, `PUT`, `DELETE` are not supported, but maybe they shouldn't be (100% support everything browsers do: `GET` and `POST`) | ||
| - Routes must be unique (i.e. no overloading `Content-Type`); it's certainly possible to get around, but you probably don't want to do that anyhow | ||
| - An `application/x-form-urlencoded` `POST` must respond with a redirect | ||
| - Currently only `String` and `Number` types are supported for Partition and Sort keys in DynamoDB | ||
| ## Next: [Check out the quickstart](/quickstart) |
| # Roadmap | ||
| `architect` is open source so you can help! Jump over to the [community page](/intro/community) to get more info about becoming a contributer. | ||
| `architect` is open source so you can help! Jump over to the [community page](/intro/community) to get more info about becoming a contributor. | ||
| ## Near-term | ||
| - `arc-functions` conslidate req / res impl | ||
| - `arc-functions` consolidate req / res impl | ||
| - `text/javascript` and `text/css` route handlers | ||
@@ -9,0 +9,0 @@ - `arc-env` infra env var and configuration management |
@@ -13,3 +13,3 @@ # Introduction | ||
| Moving from physical servers to the cloud brough significant advances to our ability to deliver software: | ||
| Moving from physical servers to the cloud brought significant advances to our ability to deliver software: | ||
@@ -16,0 +16,0 @@ - 100% utilization: only pay for what you use |
| # Setup | ||
| You'll need an Amazon Web Services account and credentials set up your development machine. | ||
| You'll need an Amazon Web Services account and credentials set up your development machine. | ||
@@ -25,3 +25,3 @@ AWS Credentials are listed in: | ||
| Having your personal AWS setup seperated from the work one is just a suggestion! (You can call them anything.) | ||
| Having your personal AWS setup separated from the work one is just a suggestion! (You can call them anything.) | ||
@@ -28,0 +28,0 @@ You can learn more about AWS creds from the source: [Amazon Configuration and Credential Files](http://docs.aws.amazon.com/cli/latest/userguide/cli-config-files.html). |
@@ -7,3 +7,3 @@ # Quickstart | ||
| ## Get started | ||
| ## Get started | ||
@@ -10,0 +10,0 @@ 1. [Set up your AWS Credentials](/quickstart/setup) |
@@ -5,3 +5,3 @@ # Workflows | ||
| - [`create`](#arc-create) creates code and corosponding cloud infrastructure | ||
| - [`create`](#arc-create) creates code and corresponding cloud infrastructure | ||
| - [`deploy`](#arc-deploy) deploys cloud functions | ||
@@ -75,3 +75,3 @@ - [`sandbox`](#arc-sandbox) runs cloud function code locally, offline and completely in memory | ||
| Start a local webserver and in-memory DyanmoDB instance: | ||
| Start a local web server and in-memory DyanmoDB instance: | ||
@@ -78,0 +78,0 @@ ```bash |
| { | ||
| "name": "@architect/docs", | ||
| "version": "30.1.11", | ||
| "version": "30.1.12", | ||
| "main": "index", | ||
@@ -5,0 +5,0 @@ "scripts": { |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Worsened metrics
- Total package byte prevSize
- decreased by-0.01%
69141
No dependency changes