├── 0000-template.md ├── README.md ├── active-rfcs └── .gitkeep └── landed-rfcs ├── 0001-ns-fonts-command.md └── 0002-webpack-rewrite.md /0000-template.md: -------------------------------------------------------------------------------- 1 | - Start Date: (fill me in with today's date, YYYY-MM-DD) 2 | - Target Major Version: (7.x / 8.x) 3 | - Reference Issues: (fill in existing related issues, if any) 4 | - Implementation PR: (leave this empty) 5 | 6 | # Summary 7 | 8 | Brief explanation of the feature. 9 | 10 | # Basic example 11 | 12 | If the proposal involves a new or changed API, include a basic code example. 13 | Omit this section if it's not applicable. 14 | 15 | # Motivation 16 | 17 | Why are we doing this? What use cases does it support? What is the expected 18 | outcome? 19 | 20 | Please focus on explaining the motivation so that if this RFC is not accepted, 21 | the motivation could be used to develop alternative solutions. In other words, 22 | enumerate the constraints you are trying to solve without coupling them too 23 | closely to the solution you have in mind. 24 | 25 | # Detailed design 26 | 27 | This is the bulk of the RFC. Explain the design in enough detail for somebody 28 | familiar with NativeScript to understand, and for somebody familiar with the 29 | implementation to implement. This should get into specifics and corner-cases, 30 | and include examples of how the feature is used. Any new terminology should be 31 | defined here. 32 | 33 | # Drawbacks 34 | 35 | Why should we *not* do this? Please consider: 36 | 37 | - implementation cost, both in term of code size and complexity 38 | - whether the proposed feature can be implemented in user space 39 | - the impact on teaching people NativeScript 40 | - integration of this feature with other existing and planned features 41 | - cost of migrating existing applications (is it a breaking change?) 42 | 43 | There are tradeoffs to choosing any path. Attempt to identify them here. 44 | 45 | # Alternatives 46 | 47 | What other designs have been considered? What is the impact of not doing this? 48 | 49 | # Adoption strategy 50 | 51 | If we implement this proposal, how will existing NativeScript developers adopt it? Is this a breaking change? Can we write a codemod? Can we provide a runtime adapter library for the original API it replaces? How will this affect other projects in the NativeScript ecosystem? 52 | 53 | # Unresolved questions 54 | 55 | Optional, but suggested for first drafts. What parts of the design are still TBD? 56 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Nativescript RFCs 2 | 3 | ## What is an RFC? 4 | 5 | The "RFC" (request for comments) process is intended to provide a 6 | consistent and controlled path for new features to enter the framework. 7 | 8 | Many changes, including bug fixes and documentation improvements can be 9 | implemented and reviewed via the normal GitHub pull request workflow. 10 | 11 | Some changes though are "substantial", and we ask that these be put 12 | through a bit of a design process and produce a consensus among the Nativescript 13 | core team and the community. 14 | 15 | ## The RFC life-cycle 16 | 17 | An RFC goes through the following stages: 18 | 19 | - **Pending:** when the RFC is submitted as a PR. 20 | - **Active:** when an RFC PR is merged and undergoing implementation. 21 | - **Landed:** when an RFC's proposed changes are shipped in an actual release. 22 | - **Rejected:** when an RFC PR is closed without being merged. 23 | 24 | [Pending RFC List](https://github.com/NativeScript/rfcs/pulls) 25 | 26 | ## When to follow this process 27 | 28 | You need to follow this process if you intend to make "substantial" 29 | changes to one of the projects listed below: 30 | 31 | - [NativeScript core/webpack](https://github.com/NativeScript/core) 32 | - [Nativescript Android Runtime](https://github.com/NativeScript/android-runtime) 33 | - [Nativescript iOS Runtime](https://github.com/NativeScript/ios-runtime) 34 | - [Nativescript iOS V8 Runtime](https://github.com/NativeScript/ns-v8ios-runtime) 35 | - [NativeScript CLI](https://github.com/NativeScript/nativescript-cli) 36 | 37 | We are limiting the RFC process for these repos to test out the process in a more manageable fashion, and may expand it to cover more projects under the `NativeScript` organization in the future. For now, if you wish to suggest changes to those other projects, please use their respective issue lists. 38 | 39 | What constitutes a "substantial" change is evolving based on community norms, but may include the following: 40 | 41 | - A new feature that creates new API surface area 42 | - Changing the semantics or behavior of an existing API 43 | - The removal of features that are already shipped as part of the release channel. 44 | - The introduction of new idiomatic usage or conventions, even if they do not include code changes to Nativescript itself. 45 | 46 | Some changes do not require an RFC: 47 | 48 | - Additions that strictly improve objective, numerical quality criteria (speedup, better runtime support) 49 | - Fixing objectively incorrect behavior 50 | - Rephrasing, reorganizing or refactoring 51 | - Addition or removal of warnings 52 | - Additions only likely to be _noticed by_ other implementors-of-Nativescript, invisible to users-of-Nativescript. 53 | 54 | If you submit a pull request to implement a new feature without going 55 | through the RFC process, it may be closed with a polite request to 56 | submit an RFC first. 57 | 58 | ## Why do you need to do this 59 | 60 | It is great that you are considering suggesting new features or changes to Nativescript - we appreciate your willingness to contribute! However, as Nativescript becomes more widely used, we need to take stability more seriously, and thus have to carefully consider the impact of every change we make that may affect end users. On the other hand, we also feel that Nativescript has reached a stage where we want to start consciously preventing further complexity from new API surfaces. 61 | 62 | These constraints and tradeoffs may not be immediately obvious to users who are proposing a change just to solve a specific problem they just ran into. The RFC process serves as a way to guide you through our thought process when making changes to Nativescript, so that we can be on the same page when discussing why or why not these changes should be made. 63 | 64 | ## Gathering feedback before submitting 65 | 66 | It's often helpful to get feedback on your concept before diving into the 67 | level of API design detail required for an RFC. **You may open a discussion on this repo to start a high-level discussion**, with the goal of 68 | eventually formulating an RFC pull request with the specific implementation 69 | design. 70 | 71 | ## What the process is 72 | 73 | In short, to get a major feature added to Nativescript, one must first get the 74 | RFC merged into the RFC repo as a markdown file. At that point the RFC 75 | is 'active' and may be implemented with the goal of eventual inclusion 76 | into Nativescript. 77 | 78 | * Fork the RFC repo http://github.com/Nativescript/rfcs 79 | 80 | * Copy `0000-template.md` to `active-rfcs/0000-my-feature.md` (where 81 | 'my-feature' is descriptive. don't assign an RFC number yet). 82 | 83 | * Fill in the RFC. Put care into the details: **RFCs that do not 84 | present convincing motivation, demonstrate understanding of the 85 | impact of the design, or are disingenuous about the drawbacks or 86 | alternatives tend to be poorly-received**. 87 | 88 | * Submit a pull request. As a pull request the RFC will receive design 89 | feedback from the larger community, and the author should be prepared 90 | to revise it in response. 91 | 92 | * Build consensus and integrate feedback. RFCs that have broad support 93 | are much more likely to make progress than those that don't receive any 94 | comments. 95 | 96 | * Eventually, the [core team] will decide whether the RFC is a candidate 97 | for inclusion in Nativescript. 98 | 99 | * An RFC can be modified based upon feedback from the [core team] and community. Significant modifications may trigger a new final comment period. 100 | 101 | * An RFC may be rejected after public discussion has settled 102 | and comments have been made summarizing the rationale for rejection. A member of the [core team] should then close the RFC's associated pull request. 103 | 104 | * An RFC may be accepted at the close of its final comment period. A [core team] member will merge the RFC's associated pull request, at which point the RFC will become 'active'. 105 | 106 | ## Details on Active RFCs 107 | 108 | Once an RFC becomes active then authors may implement it and submit the 109 | feature as a pull request to the Nativescript repo. Becoming 'active' is not a rubber 110 | stamp, and in particular still does not mean the feature will ultimately 111 | be merged; it does mean that the core team has agreed to it in principle 112 | and are amenable to merging it. 113 | 114 | Furthermore, the fact that a given RFC has been accepted and is 115 | 'active' implies nothing about what priority is assigned to its 116 | implementation, nor whether anybody is currently working on it. 117 | 118 | Modifications to active RFC's can be done in followup PR's. We strive 119 | to write each RFC in a manner that it will reflect the final design of 120 | the feature; but the nature of the process means that we cannot expect 121 | every merged RFC to actually reflect what the end result will be at 122 | the time of the next major release; therefore we try to keep each RFC 123 | document somewhat in sync with the language feature as planned, 124 | tracking such changes via followup pull requests to the document. 125 | 126 | ## Implementing an RFC 127 | 128 | The author of an RFC is not obligated to implement it. Of course, the 129 | RFC author (like any other developer) is welcome to post an 130 | implementation for review after the RFC has been accepted. 131 | 132 | An active RFC should have the link to the implementation PR listed if there is one. Feedback to the actual implementation should be conducted in the implementation PR instead of the original RFC PR. 133 | 134 | If you are interested in working on the implementation for an 'active' 135 | RFC, but cannot determine if someone else is already working on it, 136 | feel free to ask (e.g. by leaving a comment on the associated issue). 137 | 138 | ## Reviewing RFC's 139 | 140 | Members of the [core team] will attempt to review some set of open RFC 141 | pull requests on a regular basis. If a core team member believes an RFC PR is ready to be accepted into active status, they can approve the PR using GitHub's review feature to signal their approval of the RFC. 142 | 143 | **Nativescript's RFC process owes its inspiration to the [Vuejs RFC process], [React RFC process], [Rust RFC process] and [Ember RFC process]** 144 | 145 | [Vuejs RFC process]: https://github.com/vuejs/rfcs 146 | [React RFC process]: https://github.com/reactjs/rfcs 147 | [Rust RFC process]: https://github.com/rust-lang/rfcs 148 | [Ember RFC process]: https://github.com/emberjs/rfcs 149 | [Vuejs core team]: https://vuejs.org/v2/guide/team.html 150 | -------------------------------------------------------------------------------- /active-rfcs/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NativeScript/rfcs/ca7b14028f462442cf4158dc0e8f5b72ddf07782/active-rfcs/.gitkeep -------------------------------------------------------------------------------- /landed-rfcs/0001-ns-fonts-command.md: -------------------------------------------------------------------------------- 1 | - Start Date: 2020-12-21 2 | - Target Major Version: 8.x 3 | - Reference Issues: N/A 4 | - Implementation PR: https://github.com/NativeScript/nativescript-cli/pull/5452 5 | 6 | # Summary 7 | 8 | A sore spot for quite a long time is trying to get the font-family combination correct for iOS/Android. 9 | For a custom font such as barlow-bold.ttf the css needs to be: 10 | 11 | ``` 12 | font-family: Barlow, barlow-bold; 13 | ``` 14 | This feature would list all the available custom fonts with their correct form to use it in css. 15 | 16 | # Basic example 17 | 18 | Add a convenient cli command which prints out exactly what css is needed for any given font: 19 | ``` 20 | $ ns fonts 21 | 22 | Found Custom Fonts: 23 | ------------------- 24 | barlow-bold.ttf -> font-family: Barlow, barlow-bold; 25 | fontawesome.ttf -> font-family: FontAwesome, fontawesome; 26 | ``` 27 | 28 | # Motivation 29 | 30 | Getting this correct is sometimes incredibly frustrating for custom fonts. 31 | 32 | This feature would save ton of time debugging why custom fonts aren't working. 33 | 34 | # Detailed design 35 | 36 | Add a new CLI command `ns fonts` that will find a `fonts` folder in all the possible locations (`/fonts`, `//fonts` - where `` is the root of the project, and `` is the value for `appPath` in the `nativescript.config.ts` - falling back to the default value of `app` & `src`). 37 | 38 | For each font we get the metadata with a package like [font-finder](https://www.npmjs.com/package/font-finder) and then output a css string with the correct values that can be copy-pasted right into any css file from the output of the `ns fonts` command (no manualy modifications required). 39 | -------------------------------------------------------------------------------- /landed-rfcs/0002-webpack-rewrite.md: -------------------------------------------------------------------------------- 1 | - Start Date: 2020-11-13 2 | - Target Major Version: 8.x 3 | - Reference Issues: https://github.com/NativeScript/rfcs/issues/1 4 | - Implementation PR: https://github.com/NativeScript/NativeScript/pull/9038 5 | 6 | # Summary 7 | 8 | Improve usage and maintenance overhead of @nativescript/webpack 9 | 10 | 14 | 15 | # Motivation 16 | 17 | Webpack configs are currently handled by having separate config templates for different project flavors. These templates are copied in the project's root folder in an npm `postinstall` hook (unless a config already exists). The correct config is determined based on installed dependencies. 18 | 19 | Making changes to the official webpack configs is difficult as the changes usually have to be repeated for each template. After an update, users need to manually update their configs, or alternatively delete their existing ones and install `@nativescript/webpack` again in order to re-generate the config. This is generally not an issue, but many times projects need to customize the configs, making the update process even more difficult. 20 | 21 | Plugins that require modifications to the webpack config require the user to manually make the right changes to their webpack configs - these changes get lost if the config is deleted and re-generated with the `postinstall` hook. 22 | 23 | 24 | # Detailed design 25 | 26 | **For NativeScript Projects:** 27 | 28 | A new and simpler webpack config file: 29 | ```js 30 | const webpack = require('@nativescript/webpack') 31 | 32 | module.exports = env => { 33 | // initialize @nativescript/webpack with the environment 34 | webpack.init(env) 35 | 36 | // Optional: specify base config - defaults to auto-discovery 37 | webpack.useConfig('vue') 38 | 39 | // Optional: apply changes to the internal config using webpack-chain 40 | // The options object is optional 41 | const options = { 42 | order: 10 // execute "last" 43 | } 44 | webpack.chainWebpack((config, env) => { 45 | config.mode('production') // for example: force production mode 46 | }, options) 47 | 48 | // Optional: merge options into the internal config 49 | webpack.mergeWebpack({ 50 | something: true 51 | }) 52 | // or pass a function that returns an object 53 | webpack.mergeWebpack((env) => { 54 | return { 55 | something: true 56 | } 57 | }) 58 | 59 | // Optional: resolve a new instance of the chainable config 60 | // Note: this always returns a new instance of the config 61 | const config = webpack.resolveChainableConfig() 62 | 63 | // resolve a config object that webpack understands 64 | // Optionally pass in a chainable config 65 | // (from `webpack.resolveChainableConfig()` for example) 66 | // to be used, rather than creating a new instance 67 | return webpack.resolveConfig() 68 | } 69 | ``` 70 | 71 | The `chainWebpack` function accepts an optional options object: 72 | 73 | ```ts 74 | interface ChainOptions { 75 | /** 76 | * A number used to control the order in which chain functions are applied 77 | * 78 | * Recommended values: 79 | * -1 - for base configs (usually internal) 80 | * 0 - (default) 81 | * 1-9 - for related plugins to order their configs 82 | * 10 - for plugins that should apply "last" 83 | * 84 | * It's possible to set values lower than -1, or higher than 10 85 | * however it's not recommended, the default range should cover 86 | * most use-cases. 87 | */ 88 | order?: number 89 | } 90 | ``` 91 | 92 | **For 3rd party packages:** 93 | 94 | Packages can publish a `nativescript.webpack.js` file in the root directory of the package. 95 | 96 | ```js 97 | /** 98 | * This optionally provides typehints 99 | * this requires "@nativescript/webpack" to be a dependency (dev) 100 | * 101 | * @param {typeof import("@nativescript/webpack")} webpack 102 | */ 103 | module.exports = (webpack) => { 104 | // same API as the user configs 105 | // for example make changes to the internal config with webpack-chain 106 | webpack.chainWebpack((config, env) => { 107 | // as an example - add a new rule for svg files 108 | config.module 109 | .rule('svg') 110 | .test(/\.svg$/) 111 | .use('svg-loader') 112 | .loader('svg-loader') 113 | }/*, options */) 114 | } 115 | ``` 116 | 117 | When resolving the config, `@nativescript/webpack` will scan all dependencies defined in `package.json` for the `nativescript.webpack.js` file in the root directory of the package, and if found - apply it. 118 | 119 | It's only scanning packages that are defined in `package.json` since `node_modules` could potentially have thousands of dependencies that we would otherwise be scanning for each build. 120 | 121 | This has a drawback for packages that rely on transitive dependencies that provide a `nativescript.webpack.js` as those would not be discovered. The suggested workaround is for packages that rely on transitive packages, to inclue a `nativescript.webpack.js` of their own, and explicitly `require` the transitive configs: 122 | ```js 123 | // package-a/nativescript.webpack.js 124 | const packageB = require('package-b/nativescript.webpack.js') 125 | 126 | module.exports = (webpack) => { 127 | // explicitly apply packageB's configuration 128 | packageB(webpack) 129 | // ... 130 | } 131 | ``` 132 | 133 | ```js 134 | // package-b/nativescript.webpack.js 135 | 136 | module.exports = (webpack) => { 137 | // ... 138 | } 139 | ``` 140 | 141 | **Internally:** 142 | 143 | All configuration to be managed with `webpack-chain` internally. 144 | 145 | The bulk of the configuration to be managed in a `base` configuration, and only configure flavor specific additions in the flavor specific configurations: `angular`, `react`, `vue`, `svelte`, `typescript` (as flavor), `javascript` (as flavor). 146 | 147 | How the final config is constructed: 148 | 149 | The flavor is detected based on dependencies (or by explictly calling `useConfig`) and the corresponding chain function is added to the internal chain array. 150 | 151 | Dependencies are scanned for the `nativescript.webpack.js` files and executed: 152 | * calls to `chainWebpack` are pushed to the internal chain array. 153 | * calls to `mergeWebpack` are pushed to the internal merge array. 154 | 155 | The internal chain array is sorted based on the `order` values for each entry (generally ranging from -1 to 10). 156 | 157 | Each chain function is called and the internal config (chain-webpack) instance is passed along with the `env`. 158 | 159 | A new config object is created after all chain functions have been applied, and each merge config from the internal merge array is merged into the resolved config. 160 | 161 | The final config is returned by `resolveConfig` - which kicks off the whole process. 162 | 163 | # Drawbacks 164 | 165 | Configurations are managed using [webpack-chain](https://github.com/neutrinojs/webpack-chain) which has a slight learning curve, however this only applies to maintainers. 166 | 167 | # Alternatives 168 | 169 | Continuning with the templated approach, with refactors to be able to share base configurations. 170 | 171 | Merging and managing pure object-based webpack configs is error-prone and messy. 172 | 173 | # Adoption strategy 174 | 175 | A new major version of `@nativescript/webpack` would prevent existing projects from accidentally breaking (most projects have it pinned to `^3.0.0` or `~3.0.0`). 176 | 177 | To switch to the new version, developers would have to delete their `webpack.config.js` configurations (or their custom configs if not using the defaults). 178 | To generate the new config - a binary is to be provided with the new package - developers would invoke the binary with `npx @nativescript/webpack init`. 179 | 180 | BREAKING CHANGES: 181 | - `package.json` main should now use a relative path to the package.json instead of the app directory 182 | 183 | For example (given we have a `src` directory where our app is): 184 | 185 | `"main": "app.js"` becomes `"main": "src/app.js"` 186 | 187 | This simplifies things, and will allow ctrl/cmd + clicking on the filename in some editors. 188 | 189 | - `postinstall` scripts have been removed. 190 | 191 | The configuration will not need to change in the user projects between updates. 192 | 193 | For existing projects we will provide an easy upgrade path, through `ns migrate` and a binary in the package. 194 | 195 | For new projects `ns create` should create the config file by invoking a binary in the package. 196 | 197 | - removed resolutions for short imports - use full imports instead. 198 | 199 | For example: 200 | ``` 201 | import http from 'http' 202 | // becomes 203 | import { http } from '@nativescript/core' 204 | ``` 205 | 206 | # Unresolved questions 207 | 208 | - What should be the name for plugin-provided configurations? We are leaning towards `nativescript.webpack.js` in the root of the package. 209 | --------------------------------------------------------------------------------